ReadTheDocs Version:3 Jobs
##########################
-ReadTheDocs V3 jobs support documentation that is structured as a
-master documentation project plus a sub-project for each software
-component. The master project files are usually maintained in a
+ReadTheDocs Projects can be configured in a nested manner, by configuring a
+project as a subproject of another project. This allows for documentation
+projects to share a search index and a namespace or custom domain, but still be
+maintained independently.
+
+The master Read The Docs project files are usually maintained in a
"docs" git repository and should contain an index with links to all
the sub-projects. Each sub-project must maintain its documentation
files in a "docs" subdirectory within that software component's git
The RTDv3 Jenkins jobs publish documentation by triggering builds at
ReadTheDocs.io. That build process clones the appropriate repository
-and transforms Real Simple Text (RST) and other files into HTML.
-Master project builds are performed separately from sub-project
+and transforms reStructuredText (RST) and other files into HTML.
+All project's Read the Docs builds are performed separately from sub-project
builds.
-The ReadTheDocs site supports multiple versions of documentation for
+The Read The Docs site supports multiple versions of documentation for
the master project and every sub-project. Every project should have a
development branch that's published at ReadTheDocs under the title
"latest"; in git this is usually the "master" branch. Most projects
User setup
----------
-To transform your rst documentation into a read the docs page, this job must be
+To transform your rst documentation into a Read The Docs page, this job must be
configured and created as described in Admin setup below. Once this is complete
the following files must be added to your repository:
path in the tox run has changed.
-Once these files are correctly configured in your repository you can test
-locally:
+Once these files are correctly configured in your repository you can build
+the rst files locally to test:
.. code-block:: bash
--------------------------
If your project does not create branches, you can skip this step.
-Once you branch your project modify your conf.yaml and add the following line:
-
-.. code-block:: bash
-
- version: 'ReleaseBranchName'
-
-This will update the docs and change "master" on the top bar to your branch
-name. This change should be done against your release branch, this change will
-trigger a Read The Docs build which will create a new landing point for your
-documentation.
-This landing point is called /stable/ and is selectable as a version in the
-bottom right corner of all Read The Docs pages. Once all projects have
-branched and modified their conf.py they will have available their /stable/
-documentation. The process to release the documentation (that is to change the
-default landing point of your docs from /latest/ to /stable/) is to change the
-default-version in the jenkins job config as follows:
+For Read The Docs to see your new branch, a build needs to be triggered.
+A trivial change to any file in your project's /docs/ directory
+on your newly minted branch is sufficient to build and activate your project's
+new branch on Read The Docs. This will create a new selectable version
+in the bottom right corner of your project's Read The Docs page.
+Once all projects have branched the process to release the documentation
+(that is to change the default landing point of your docs from /latest/ to /branchname/)
+is to change the default-version in the jenkins job config as follows:
From:
Admin setup:
+------------
-This is a global job that only needs to be added once to your project's ci-mangement git
-repository. It leverages the read the docs v3 api to create projects on the fly, as well
-as setting up subproject associations with the master doc.
+This part of the documentation explains how to enable this job so that It will trigger
+on docs/* changes for all projects in a Gerrit instance. It leverages the
+Read The Docs v3 api to create projects on the fly, as well as setting up
+sub-project associations with the master doc.
Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the
root of the repository
- master:
branch: '*'
-Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
+Github jobs must be per project, and will be covered by a different set of jobs once these are proven.
Job requires an lftools config section, this is to provide api access to read the docs.
endpoint = https://readthedocs.org/api/v3/
token = [hidden]
-Merge Job will create a project on read the docs if none exist.
+Merge Job will create a project on Read The Docs if none exist.
Merge Job will assign a project as a subproject of the master project.
Merge job will trigger a build to update docs.
Merge job will change the default version if needed.
ReadTheDocs v3 Merge
--------------------
-Merge job which triggers a build of the docs to readthedocs.
+Merge job which triggers a build of the docs to Read The Docs.
:Template Names:
- rtdv3-global-merge-{stream}
(default: 10)
:submodule-disable: Disable submodule checkout operation.
(default: false)
- :tox-dir: Directory containing the project's read the docs tox.ini
+ :tox-dir: Directory containing the project's Read The Docs tox.ini
:doc-dir: Relative directory project's docs generated by tox
:gerrit_merge_triggers: Override Gerrit Triggers.
:gerrit_trigger_file_paths: Override file paths filter which checks which
(default: 10)
:submodule-disable: Disable submodule checkout operation.
(default: false)
- :tox-dir: Directory containing the project's read the docs tox.ini
+ :tox-dir: Directory containing the project's Read The Docs tox.ini
:doc-dir: Relative directory project's docs generated by tox
:gerrit_verify_triggers: Override Gerrit Triggers.
:gerrit_trigger_file_paths: Override file paths filter which checks which
project: "{project}"
stream: "{stream}"
branch: "{branch}"
+ - lf-infra-jjb-parameters:
+ jjb-cache: "{jjb-cache}"
+ jjb-version: "{jjb-version}"
wrappers:
- lf-infra-wrappers:
- job-template:
name: "{project-name}-jjb-deploy-job"
id: gerrit-jjb-deploy-job
+ <<: *lf_jjb_common
+ # yamllint disable-line rule:key-duplicates
<<: *lf_jjb_deploy_job
scm:
- job-template:
name: "{project-name}-jjb-deploy-job"
id: github-jjb-deploy-job
+ <<: *lf_jjb_common
+ # yamllint disable-line rule:key-duplicates
<<: *lf_jjb_deploy_job
properties:
<<: *lf_sonar_builders_prescan_script
# yamllint disable-line rule:key-duplicates
<<: *lf_sonar_github_common
+
+#############
+# Pipelines #
+#############
+
+- lf_pipelines_common: &lf_pipelines_common
+ name: lf-pipelines-common
+
+ ######################
+ # Default parameters #
+ ######################
+
+ branch: master
+ build-timeout: 90
+ disable-job: false
+ stream: master
+ submodule-recursive: true
+ submodule-timeout: 10
+ submodule-disable: false
+
+- lf_global_pipelines_common: &lf_global_pipelines_common
+ name: lf-global-pipelines-common
+
+ # All jobs are triggering from the same source
+ git-url: https://gerrit.linuxfoundation.org/infra/releng/pipelines
+ triggers:
+ - gerrit:
+ server-name: "lf-releng"
+ trigger-on:
+ - patchset-created-event:
+ exclude-drafts: true
+ exclude-trivial-rebase: false
+ exclude-no-code-change: false
+ - draft-published-event
+ - comment-added-contains-event:
+ comment-contains-value: '^Patch Set\s+\d+:\s+(recheck|reverify)\s*$'
+ projects:
+ - project-compare-type: ANT
+ project-pattern: "releng/pipelines"
+ branches:
+ - branch-compare-type: ANT
+ branch-pattern: "**/master"
+
+- job-template:
+ name: "lf-pipelines-verify"
+ id: lf-pipelines-verify
+ <<: *lf_pipelines_common
+ <<: *lf_global_pipelines_common
+
+ project-type: pipeline
+ pipeline-scm:
+ scm:
+ - lf-infra-gerrit-scm:
+ git-url: "{git-url}"
+ refspec: "$GERRIT_REFSPEC"
+ branch: "$GERRIT_BRANCH"
+ submodule-recursive: "{submodule-recursive}"
+ submodule-timeout: "{submodule-timeout}"
+ submodule-disable: "{submodule-disable}"
+ choosing-strategy: gerrit
+ jenkins-ssh-credential: "{jenkins-ssh-credential}"
+ sandbox: true
Code Review / releng / global-jjb.git / commitdiff