1 .. _lf-global-jjb-rtdv3-jobs:
3 ##########################
4 ReadTheDocs Version:3 Jobs
5 ##########################
7 ReadTheDocs Projects can be configured in a nested manner, by configuring a
8 project as a subproject of another project. This allows for documentation
9 projects to share a search index and a namespace or custom domain, but still be
10 maintained independently.
12 The master Read The Docs project files are usually maintained in a
13 "docs" git repository and should contain an index with links to all
14 the sub-projects. Each sub-project must maintain its documentation
15 files in a "docs" subdirectory within that software component's git
18 The RTDv3 Jenkins jobs publish documentation by triggering builds at
19 ReadTheDocs.io. That build process clones the appropriate repository
20 and transforms reStructuredText (RST) and other files into HTML.
21 All project's Read the Docs builds are performed separately from sub-project
24 The Read The Docs site supports multiple versions of documentation for
25 the master project and every sub-project. Every project should have a
26 development branch that's published at ReadTheDocs under the title
27 "latest"; in git this is usually the "master" branch. Most projects
28 also declare releases periodically. ReadTheDocs automatically detects
29 the creation of git branches and git tags, and publishes the most
30 recent one under the title "stable." For more details please see
32 <https://docs.readthedocs.io/en/stable/versions.html>`_. Teams can
33 control this process using Jenkins job configuration parameters as
39 To transform your rst documentation into a Read The Docs page, this job must be
40 configured and created as described in Admin setup below. Once this is complete
41 the following files must be added to your repository:
53 docs/requirements-docs.txt
56 Rather than have you copy and paste these files from a set of docs here, the
57 following repo contains a script that will do this for you. Please refer to the
58 explanation presented in: https://github.com/lfit-sandbox/test. This is all
59 currently a beta feature, so feedback is encouraged. The script
60 ``docs_script.sh`` is not needed, you can copy the files by hand if you prefer.
62 The default location of the tox.ini file is in the git repository root
63 directory. Optionally your documentation lead may decide to store all tox files
64 within the required "docs" subdirectory by setting configuration option
65 "tox-dir" to value "docs/" as discussed below.
67 If your project's tox dir is "docs/" and not "." the tox.ini must be
68 reconfigured with the correct relative paths.
70 Additionally, you must also modify the doc-dir. For example, from the default
71 of ``doc-dir: "docs/_build/html"`` to ``doc-dir: "_build/html"``, as the relative
72 path in the tox run has changed.
75 Once these files are correctly configured in your repository you can build
76 the rst files locally to test:
80 tox -e docs,docs-linkcheck
83 Stable Branch Instructions
84 --------------------------
86 If your project does not create branches, you can skip this step.
88 For Read The Docs to see your new branch, a build needs to be triggered.
89 A trivial change to any file in your project's /docs/ directory
90 on your newly minted branch is sufficient to build and activate your project's
91 new branch on Read The Docs. This will create a new selectable version
92 in the bottom right corner of your project's Read The Docs page.
93 Once all projects have branched the process to release the documentation
94 (that is to change the default landing point of your docs from /latest/ to /branchname/)
95 is to change the default-version in the jenkins job config as follows:
101 default-version: latest
107 default-version: ReleaseBranchName
113 This part of the documentation explains how to enable this job so that It will trigger
114 on docs/* changes for all projects in a Gerrit instance. It leverages the
115 Read The Docs v3 api to create projects on the fly, as well as setting up
116 sub-project associations with the master doc.
118 Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the
119 root of the repository
121 The master doc must be defined in
122 jenkins-config/global-vars-{production|sandbox}.sh
124 Normally this project is called doc or docs or documentation and all other docs build will
125 be set as a subproject of this job.
131 global-vars-sandbox.sh:
132 MASTER_RTD_PROJECT=doc-test
133 global-vars-production.sh:
134 MASTER_RTD_PROJECT=doc
136 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
141 example file: ci-management/jjb/rtd/rtd.yaml
147 name: rtdv3-global-verify
148 build-node: centos7-builder-1c-1g
149 default-version: latest
151 doc-dir: "docs/_build/html"
153 - rtdv3-global-verify
158 branch: stable/{stream}
161 name: rtdv3-global-merge
162 default-version: latest
164 doc-dir: "docs/_build/html"
165 build-node: centos7-builder-1c-1g
172 branch: stable/{stream}
174 Or add both jobs via a job group:
175 This real-world example also shows how to configure your builds to use
176 a tox.ini that lived inside your docs/ dir
181 # Global read the docs version 3 jobs
183 # jobs trigger for all projects, all branches
184 # on any changes to files in a docs/ directory
185 # and publish subprojects to readthedocs.io
186 # using credentials from Jenkins settings
190 project-name: rtdv3-global
196 default-version: latest
198 doc-dir: "_build/html"
199 build-node: centos7-builder-2c-1g
200 # override the default to ignore ref-updated-event (tag)
201 gerrit_merge_triggers:
202 - change-merged-event
203 - comment-added-contains-event:
204 comment-contains-value: remerge$
206 - rtdv3-global-verify
212 Github jobs must be per project, and will be covered by a different set of jobs once these are proven.
214 Job requires an lftools config section, this is to provide api access to read the docs.
219 endpoint = https://readthedocs.org/api/v3/
222 Merge Job will create a project on Read The Docs if none exist.
223 Merge Job will assign a project as a subproject of the master project.
224 Merge job will trigger a build to update docs.
225 Merge job will change the default version if needed.
233 RTD verify and merge jobs are the same except for their scm, trigger, and
234 builders definition. This anchor is the common template.
243 Merge job which triggers a build of the docs to Read The Docs.
246 - rtdv3-global-merge-{stream}
248 :Comment Trigger: remerge
250 :Required parameters:
252 :build-node: The node to run build on.
253 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
256 :Optional parameters:
258 :branch: Git branch to fetch for the build. (default: master)
259 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
260 :build-timeout: Timeout in minutes before aborting build. (default: 15)
261 :default-version: default page to redirect to for documentation (default /latest/)
262 :disable-job: Whether to disable the job (default: false)
263 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
264 :project-pattern: Project to trigger build against. (default: \*\*)
265 :stream: Keyword representing a release code-name.
266 Often the same as the branch. (default: master)
267 :submodule-recursive: Whether to checkout submodules recursively.
269 :submodule-timeout: Timeout (in minutes) for checkout operation.
271 :submodule-disable: Disable submodule checkout operation.
273 :tox-dir: Directory containing the project's Read The Docs tox.ini
274 :doc-dir: Relative directory project's docs generated by tox
275 :gerrit_merge_triggers: Override Gerrit Triggers.
276 :gerrit_trigger_file_paths: Override file paths filter which checks which
277 file modifications will trigger a build.
280 - compare-type: REG_EXP
284 ReadTheDocs v3 Verify
285 ---------------------
287 Verify job which runs a tox build of the docs project.
288 Also outputs some info on the build.
291 - rtdv3-global-verify-{stream}
293 :Comment Trigger: recheck|reverify
295 :Required Parameters:
297 :build-node: The node to run build on.
298 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
301 :Optional Parameters:
303 :branch: Git branch to fetch for the build. (default: master)
304 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
305 :build-timeout: Timeout in minutes before aborting build. (default: 15)
306 :gerrit-skip-vote: Skip voting for this job. (default: false)
307 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
308 :disable-job: Whether to disable the job (default: false)
309 :project-pattern: Project to trigger build against. (default: \*\*)
310 :stream: Keyword representing a release code-name.
311 Often the same as the branch. (default: master)
312 :submodule-recursive: Whether to checkout submodules recursively.
314 :submodule-timeout: Timeout (in minutes) for checkout operation.
316 :submodule-disable: Disable submodule checkout operation.
318 :tox-dir: Directory containing the project's Read The Docs tox.ini
319 :doc-dir: Relative directory project's docs generated by tox
320 :gerrit_verify_triggers: Override Gerrit Triggers.
321 :gerrit_trigger_file_paths: Override file paths filter which checks which
322 file modifications will trigger a build.
325 - compare-type: REG_EXP