1 .. _lf-global-jjb-rtdv3-jobs:
3 ##########################
4 ReadTheDocs Version:3 Jobs
5 ##########################
7 ReadTheDocs supports the nesting of projects, by configuring a project as a
8 subproject of another project. This allows for documentation projects to share
9 a search index and a namespace or custom domain, while still maintained
10 independently of each other.
12 The master Read The Docs project files, maintained in a "docs" Git repository
13 should contain an index with links to all the sub-projects. Each sub-project
14 must maintain its documentation files in a "docs" subdirectory within that
15 software component's Git repository.
17 The RTDv3 Jenkins jobs publish documentation by triggering builds at
18 ReadTheDocs.io. That build process clones the appropriate repository
19 and transforms reStructuredText (RST) and other files into HTML.
20 All project's Read the Docs builds separately from sub-project builds.
22 The Read The Docs site supports versioned documentation for the master project
23 and every sub-project. Every project should have a development branch that's
24 published at ReadTheDocs under the title "latest"; in Git this is the "master"
25 branch although can be different in some projects. Most projects also declare
26 releases periodically. ReadTheDocs automatically detects the creation of git
27 branches and git tags, and publishes the most recent one under the title
28 "stable." For more details please see `ReadTheDocs Versions
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, configure as
37 described in Admin setup below. Once this is complete, add the following files
50 docs/requirements-docs.txt
53 Rather than copying and pasting 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 a
56 beta feature, so please send feedback on your experiences. Once complete, the
57 script ``docs_script.sh`` is not needed. You can copy the files by hand if you
60 The default location of the tox.ini file is in the git repository root
61 directory. Optionally your documentation lead may decide to store all tox files
62 within the required "docs" subdirectory by setting configuration option
63 "tox-dir" to value "docs/" as discussed below.
65 If your project's tox dir is ``docs/`` and not ``.``, update the tox.ini
66 configuration with the correct relative paths.
68 You must also set the doc-dir. For example, from the default of
69 ``doc-dir: "docs/_build/html"`` to ``doc-dir: "_build/html"``, as the relative
70 path in the tox run has changed.
72 Once configured, in your repository you can build the rst files locally to
77 tox -e docs,docs-linkcheck
80 Stable Branch Instructions
81 --------------------------
83 If your project does not create branches, you can skip this step.
85 For Read The Docs to see your new branch, trigger a build to force RTD to run
86 an update. Use a trivial change to any file in your project's ``/docs/``
87 directory on your newly minted branch to trigger a build and activate your
88 project's new branch on Read The Docs. This will create a new selectable
89 version in the bottom right corner of your project's Read The Docs page.
90 Once all projects have branched the process to release the documentation
91 (that is to change the default landing point of your docs from /latest/ to /branchname/)
92 is to change the default-version in the jenkins job config as follows:
98 default-version: latest
104 default-version: ReleaseBranchName
110 This part of the documentation explains how to enable this job so that It will trigger
111 on docs/* changes for all projects in a Gerrit instance. It leverages the
112 Read The Docs v3 api to create projects on the fly, as well as setting up
113 sub-project associations with the master doc.
115 A ``.readthedocs.yaml`` must exist in the root of the repository otherwise the
116 jobs will run but skip actual verification.
118 Define the master doc in jenkins-config/global-vars-{production|sandbox}.sh
120 This project named "doc" or "docs" or "documentation" will set all other docs
121 builds as a subproject of this job.
127 global-vars-sandbox.sh:
128 MASTER_RTD_PROJECT=doc-test
129 global-vars-production.sh:
130 MASTER_RTD_PROJECT=doc
132 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
137 example file: ci-management/jjb/rtd/rtd.yaml
143 name: rtdv3-global-verify
144 build-node: centos7-builder-1c-1g
145 default-version: latest
147 doc-dir: "docs/_build/html"
149 - rtdv3-global-verify
154 branch: stable/{stream}
157 name: rtdv3-global-merge
158 default-version: latest
160 doc-dir: "docs/_build/html"
161 build-node: centos7-builder-1c-1g
168 branch: stable/{stream}
170 Or add both jobs via a job group:
171 This real-world example also shows how to configure your builds to use
172 a tox.ini that lived inside your docs/ dir
177 # Global read the docs version 3 jobs
179 # jobs trigger for all projects, all branches
180 # on any changes to files in a docs/ directory
181 # and publish subprojects to readthedocs.io
182 # using credentials from Jenkins settings
186 project-name: rtdv3-global
192 default-version: latest
194 doc-dir: "_build/html"
195 build-node: centos7-builder-2c-1g
196 # override the default to ignore ref-updated-event (tag)
197 gerrit_merge_triggers:
198 - change-merged-event
199 - comment-added-contains-event:
200 comment-contains-value: remerge$
202 - rtdv3-global-verify
208 GitHub jobs must be per-project. Once proven, a different set of jobs will be available.
210 Job requires an lftools config section, this is to provide api access to read the docs.
215 endpoint = https://readthedocs.org/api/v3/
218 Merge Job will create a project on Read The Docs if none exist.
219 Merge Job will assign a project as a subproject of the master project.
220 Merge job will trigger a build to update docs.
221 Merge job will change the default version if needed.
229 RTD verify and merge jobs are the same except for their scm, trigger, and
230 builders definition. This anchor is the common template.
239 Merge job which triggers a build of the docs to Read The Docs.
242 - rtdv3-global-merge-{stream}
244 :Comment Trigger: remerge
246 :Required parameters:
248 :build-node: The node to run build on.
249 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
252 :Optional parameters:
254 :branch: Git branch to fetch for the build. (default: master)
255 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
256 :build-timeout: Timeout in minutes before aborting build. (default: 15)
257 :default-version: default page to redirect to for documentation (default /latest/)
258 :disable-job: Whether to disable the job (default: false)
259 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
260 :project-pattern: Project to trigger build against. (default: \*\*)
261 :stream: Keyword representing a release code-name.
262 Often the same as the branch. (default: master)
263 :submodule-recursive: Whether to checkout submodules recursively.
265 :submodule-timeout: Timeout (in minutes) for checkout operation.
267 :submodule-disable: Disable submodule checkout operation.
269 :tox-dir: Directory containing the project's Read The Docs tox.ini
270 :doc-dir: Relative directory project's docs generated by tox
271 :gerrit_merge_triggers: Override Gerrit Triggers.
272 :gerrit_trigger_file_paths: Override file paths filter which checks which
273 file modifications will trigger a build.
276 - compare-type: REG_EXP
280 ReadTheDocs v3 Verify
281 ---------------------
283 Verify job which runs a tox build of the docs project.
284 Also outputs some info on the build.
287 - rtdv3-global-verify-{stream}
289 :Comment Trigger: recheck|reverify
291 :Required Parameters:
293 :build-node: The node to run build on.
294 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
297 :Optional Parameters:
299 :branch: Git branch to fetch for the build. (default: master)
300 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
301 :build-timeout: Timeout in minutes before aborting build. (default: 15)
302 :gerrit-skip-vote: Skip voting for this job. (default: false)
303 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
304 :disable-job: Whether to disable the job (default: false)
305 :project-pattern: Project to trigger build against. (default: \*\*)
306 :stream: Keyword representing a release code-name.
307 Often the same as the branch. (default: master)
308 :submodule-recursive: Whether to checkout submodules recursively.
310 :submodule-timeout: Timeout (in minutes) for checkout operation.
312 :submodule-disable: Disable submodule checkout operation.
314 :tox-dir: Directory containing the project's Read The Docs tox.ini
315 :doc-dir: Relative directory project's docs generated by tox
316 :gerrit_verify_triggers: Override Gerrit Triggers.
317 :gerrit_trigger_file_paths: Override file paths filter which checks which
318 file modifications will trigger a build.
321 - compare-type: REG_EXP