1 .. _lf-global-jjb-rtdv3-jobs:
3 ##########################
4 ReadTheDocs Version:3 Jobs
5 ##########################
9 To transform your rst documentation into a read the docs page, this job must be configured and
10 created as described in Admin setup below. Once this is complete the following files must be
11 added to your repository:
23 docs/requirements-docs.txt
26 Rather than have you copy and paste these files from a set of docs here, the following repo
27 contains a script that will do this for you. Please refer to the explanation presented in:
28 https://github.com/lfit-sandbox/test
29 This is all currently a beta feature, so feedback is encouraged.
30 the script `docs_script.sh` is not needed, you can copy the files by hand if you prefer
32 Once these files are correctly configured in your repository you can test locally:
36 tox -e docs,docs-linkcheck
41 This is a global job that only needs to be added once to your project's ci-mangement git
42 repository. It leverages the read the docs v3 api to create projects on the fly, as well
43 as setting up subproject associations with the master doc.
45 Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the
46 root of the repository
48 The master doc must be defined in
49 jenkins-config/global-vars-{production|sandbox}.sh
51 Normally this project is called doc or docs or documentation and all other docs build will
52 be set as a subproject of this job.
55 global-vars-sandbox.sh:
56 MASTER_RTD_PROJECT=doc-test
57 global-vars-production.sh:
58 MASTER_RTD_PROJECT=doc
60 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
65 example file: ci-management/jjb/rtd/rtd.yaml
71 name: rtdv3-global-verify
72 build-node: centos7-builder-1c-1g
79 branch: stable/{stream}
82 name: rtdv3-global-merge
83 build-node: centos7-builder-1c-1g
90 branch: stable/{stream}
92 Or add both jobs via a job group:
100 build-node: centos7-builder-1c-1g
108 Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
110 Job requires an lftools config section, this is to provide api access to read the docs.
115 endpoint = https://readthedocs.org/api/v3/
118 Merge Job will create a project on read the docs if none exist.
119 Merge Job will assign a project as a subproject of the master project.
120 Merge job will trigger a build to update docs.
128 RTD verify and merge jobs are the same except for their scm, trigger, and
129 builders definition. This anchor is the common template.
138 Merge job which triggers a build of the docs to readthedocs.
141 - rtdv3-global-merge-{stream}
143 :Comment Trigger: remerge
145 :Required parameters:
147 :build-node: The node to run build on.
148 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
151 :Optional parameters:
153 :branch: Git branch to fetch for the build. (default: master)
154 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
155 :build-timeout: Timeout in minutes before aborting build. (default: 15)
156 :project-pattern: Project to trigger build against. (default: \*\*)
157 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
158 :disable-job: Whether to disable the job (default: false)
159 :stream: Keyword representing a release code-name.
160 Often the same as the branch. (default: master)
161 :submodule-recursive: Whether to checkout submodules recursively.
163 :submodule-timeout: Timeout (in minutes) for checkout operation.
165 :submodule-disable: Disable submodule checkout operation.
168 :gerrit_merge_triggers: Override Gerrit Triggers.
169 :gerrit_trigger_file_paths: Override file paths filter which checks which
170 file modifications will trigger a build.
173 - compare-type: REG_EXP
177 ReadTheDocs v3 Verify
178 ---------------------
180 Verify job which runs a tox build of the docs project.
181 Also outputs some info on the build.
184 - rtdv3-global-verify-{stream}
186 :Comment Trigger: recheck|reverify
188 :Required Parameters:
190 :build-node: The node to run build on.
191 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
194 :Optional Parameters:
196 :branch: Git branch to fetch for the build. (default: master)
197 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
198 :build-timeout: Timeout in minutes before aborting build. (default: 15)
199 :gerrit-skip-vote: Skip voting for this job. (default: false)
200 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
201 :disable-job: Whether to disable the job (default: false)
202 :project-pattern: Project to trigger build against. (default: \*\*)
203 :stream: Keyword representing a release code-name.
204 Often the same as the branch. (default: master)
205 :submodule-recursive: Whether to checkout submodules recursively.
207 :submodule-timeout: Timeout (in minutes) for checkout operation.
209 :submodule-disable: Disable submodule checkout operation.
212 :gerrit_verify_triggers: Override Gerrit Triggers.
213 :gerrit_trigger_file_paths: Override file paths filter which checks which
214 file modifications will trigger a build.
217 - compare-type: REG_EXP