1 .. _lf-global-jjb-rtdv3-jobs:
3 ##########################
4 ReadTheDocs Version:3 Jobs
5 ##########################
7 ReadTheDocs V3 jobs support documentation that is structured as a
8 master documentation project plus a sub-project for each software
9 component. The master project files are usually maintained in a
10 "docs" git repository and should contain an index with links to all
11 the sub-projects. Each sub-project must maintain its documentation
12 files in a "docs" subdirectory within that software component's git
15 The RTDv3 Jenkins jobs publish documentation by triggering builds at
16 ReadTheDocs.io. That build process clones the appropriate repository
17 and transforms Real Simple Text (RST) and other files into HTML.
18 Master project builds are performed separately from sub-project
21 The ReadTheDocs site supports multiple versions of documentation for
22 the master project and every sub-project. Every project should have a
23 development branch that's published at ReadTheDocs under the title
24 "latest"; in git this is usually the "master" branch. Most projects
25 also declare releases periodically. ReadTheDocs automatically detects
26 the creation of git branches and git tags, and publishes the most
27 recent one under the title "stable." For more details please see
29 <https://docs.readthedocs.io/en/stable/versions.html>`_. Teams can
30 control this process using Jenkins job configuration parameters as
36 To transform your rst documentation into a read the docs page, this job must be
37 configured and created as described in Admin setup below. Once this is complete
38 the following files must be added to your repository:
50 docs/requirements-docs.txt
53 Rather than have you copy and paste these files from a set of docs here, the
54 following repo contains a script that will do this for you. Please refer to the
55 explanation presented in: https://github.com/lfit-sandbox/test. This is all
56 currently a beta feature, so feedback is encouraged. The script
57 ``docs_script.sh`` is not needed, you can copy the files by hand if you prefer.
59 The default location of the tox.ini file is in the git repository root
60 directory. Optionally your documentation lead may decide to store all tox files
61 within the required "docs" subdirectory by setting configuration option
62 "tox-dir" to value "docs/" as discussed below.
64 If your project's tox dir is "docs/" and not "." the tox.ini must be
65 reconfigured with the correct relative paths.
67 Additionally, you must also modify the doc-dir. For example, from the default
68 of ``doc-dir: "docs/_build/html"`` to ``doc-dir: "_build/html"``, as the relative
69 path in the tox run has changed.
72 Once these files are correctly configured in your repository you can test
77 tox -e docs,docs-linkcheck
80 Stable Branch Instructions
81 --------------------------
83 If your project does not create branches, you can skip this step.
84 Once you branch your project modify your conf.yaml and add the following line:
88 version: 'ReleaseBranchName'
90 This will update the docs and change "master" on the top bar to your branch
91 name. This change should be done against your release branch, this change will
92 trigger a Read The Docs build which will create a new landing point for your
95 This landing point is called /stable/ and is selectable as a version in the
96 bottom right corner of all Read The Docs pages. Once all projects have
97 branched and modified their conf.py they will have available their /stable/
98 documentation. The process to release the documentation (that is to change the
99 default landing point of your docs from /latest/ to /stable/) is to change the
100 default-version in the jenkins job config as follows:
106 default-version: latest
112 default-version: ReleaseBranchName
117 This is a global job that only needs to be added once to your project's ci-mangement git
118 repository. It leverages the read the docs v3 api to create projects on the fly, as well
119 as setting up subproject associations with the master doc.
121 Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the
122 root of the repository
124 The master doc must be defined in
125 jenkins-config/global-vars-{production|sandbox}.sh
127 Normally this project is called doc or docs or documentation and all other docs build will
128 be set as a subproject of this job.
134 global-vars-sandbox.sh:
135 MASTER_RTD_PROJECT=doc-test
136 global-vars-production.sh:
137 MASTER_RTD_PROJECT=doc
139 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
144 example file: ci-management/jjb/rtd/rtd.yaml
150 name: rtdv3-global-verify
151 build-node: centos7-builder-1c-1g
152 default-version: latest
154 doc-dir: "docs/_build/html"
156 - rtdv3-global-verify
161 branch: stable/{stream}
164 name: rtdv3-global-merge
165 default-version: latest
167 doc-dir: "docs/_build/html"
168 build-node: centos7-builder-1c-1g
175 branch: stable/{stream}
177 Or add both jobs via a job group:
178 This real-world example also shows how to configure your builds to use
179 a tox.ini that lived inside your docs/ dir
184 # Global read the docs version 3 jobs
186 # jobs trigger for all projects, all branches
187 # on any changes to files in a docs/ directory
188 # and publish subprojects to readthedocs.io
189 # using credentials from Jenkins settings
193 project-name: rtdv3-global
199 default-version: latest
201 doc-dir: "_build/html"
202 build-node: centos7-builder-2c-1g
203 # override the default to ignore ref-updated-event (tag)
204 gerrit_merge_triggers:
205 - change-merged-event
206 - comment-added-contains-event:
207 comment-contains-value: remerge$
209 - rtdv3-global-verify
215 Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
217 Job requires an lftools config section, this is to provide api access to read the docs.
222 endpoint = https://readthedocs.org/api/v3/
225 Merge Job will create a project on read the docs if none exist.
226 Merge Job will assign a project as a subproject of the master project.
227 Merge job will trigger a build to update docs.
228 Merge job will change the default version if needed.
236 RTD verify and merge jobs are the same except for their scm, trigger, and
237 builders definition. This anchor is the common template.
246 Merge job which triggers a build of the docs to readthedocs.
249 - rtdv3-global-merge-{stream}
251 :Comment Trigger: remerge
253 :Required parameters:
255 :build-node: The node to run build on.
256 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
259 :Optional parameters:
261 :branch: Git branch to fetch for the build. (default: master)
262 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
263 :build-timeout: Timeout in minutes before aborting build. (default: 15)
264 :default-version: default page to redirect to for documentation (default /latest/)
265 :disable-job: Whether to disable the job (default: false)
266 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
267 :project-pattern: Project to trigger build against. (default: \*\*)
268 :stream: Keyword representing a release code-name.
269 Often the same as the branch. (default: master)
270 :submodule-recursive: Whether to checkout submodules recursively.
272 :submodule-timeout: Timeout (in minutes) for checkout operation.
274 :submodule-disable: Disable submodule checkout operation.
276 :tox-dir: Directory containing the project's read the docs tox.ini
277 :doc-dir: Relative directory project's docs generated by tox
278 :gerrit_merge_triggers: Override Gerrit Triggers.
279 :gerrit_trigger_file_paths: Override file paths filter which checks which
280 file modifications will trigger a build.
283 - compare-type: REG_EXP
287 ReadTheDocs v3 Verify
288 ---------------------
290 Verify job which runs a tox build of the docs project.
291 Also outputs some info on the build.
294 - rtdv3-global-verify-{stream}
296 :Comment Trigger: recheck|reverify
298 :Required Parameters:
300 :build-node: The node to run build on.
301 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
304 :Optional Parameters:
306 :branch: Git branch to fetch for the build. (default: master)
307 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
308 :build-timeout: Timeout in minutes before aborting build. (default: 15)
309 :gerrit-skip-vote: Skip voting for this job. (default: false)
310 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
311 :disable-job: Whether to disable the job (default: false)
312 :project-pattern: Project to trigger build against. (default: \*\*)
313 :stream: Keyword representing a release code-name.
314 Often the same as the branch. (default: master)
315 :submodule-recursive: Whether to checkout submodules recursively.
317 :submodule-timeout: Timeout (in minutes) for checkout operation.
319 :submodule-disable: Disable submodule checkout operation.
321 :tox-dir: Directory containing the project's read the docs tox.ini
322 :doc-dir: Relative directory project's docs generated by tox
323 :gerrit_verify_triggers: Override Gerrit Triggers.
324 :gerrit_trigger_file_paths: Override file paths filter which checks which
325 file modifications will trigger a build.
328 - compare-type: REG_EXP