8f85f1a9218f9b59eb676a7fcae401e5891ec885
[releng/global-jjb.git] / lf-rtd-jobs.rst
1 .. _lf-global-jjb-rtd-jobs:
2
3 ################
4 ReadTheDocs Jobs
5 ################
6
7 Job Groups
8 ==========
9
10 {project-name}-rtd-jobs
11 -----------------------
12
13 Jobs to deploy for a project producing ReadTheDocs using Gerrit.
14
15 :Includes:
16
17     - gerrit-rtd-merge
18     - gerrit-rtd-verify
19
20 {project-name}-github-rtd-jobs
21 ------------------------------
22
23 Jobs to deploy for a project producing ReadTheDocs using GitHub.
24
25 :Includes:
26
27     - github-rtd-merge
28     - github-rtd-verify
29
30
31 Macros
32 ======
33
34 lf-rtd-common
35 -------------
36
37 RTD verify and merge jobs are the same except for their scm, trigger, and
38 builders definition. This anchor is the common template.
39
40
41 Job Templates
42 =============
43
44 ReadTheDocs Merge
45 -----------------
46
47 Merge job which triggers a POST of the docs project to readthedocs
48
49 :Template Names:
50     - {project-name}-rtd-merge-{stream}
51     - gerrit-rtd-merge
52     - github-rtd-merge
53
54 :Required parameters:
55
56     :build-node: The node to run build on.
57     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
58         in defaults.yaml)
59     :rtd-project: This is the name of the project on ReadTheDocs.org.
60
61 :Optional parameters:
62
63     :branch: Git branch to fetch for the build. (default: master)
64     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
65     :build-timeout: Timeout in seconds before aborting build. (default: 15)
66     :git-url: base URL of git project. (default: https://github.com)
67     :project-pattern: Project to trigger build against. (default: \*\*)
68     :stream: Keyword representing a release code-name.
69         Often the same as the branch. (default: master)
70     :submodule-recursive: Whether to checkout submodules recursively.
71         (default: true)
72
73     :gerrit_merge_triggers: Override Gerrit Triggers.
74     :gerrit_trigger_file_paths: Override file paths filter which checks which
75         file modifications will trigger a build.
76         **default**::
77
78             - compare-type: ANT
79               pattern: '**/*.rst'
80             - compare-type: ANT
81               pattern: '**/conf.py'
82
83
84 ReadTheDocs Verify
85 ------------------
86
87 Verify job which runs a tox build of the docs project
88
89 :Template Names:
90     - {project-name}-rtd-verify-{stream}
91     - gerrit-rtd-verify
92     - github-rtd-verify
93
94 :Required Parameters:
95
96     :build-node: The node to run build on.
97     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
98         in defaults.yaml)
99
100 :Optional Parameters:
101
102     :branch: Git branch to fetch for the build. (default: master)
103     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
104     :build-node: The node to run build on.
105     :build-timeout: Timeout in seconds before aborting build. (default: 15)
106     :doc-dir: Directory where tox will place built docs.
107         as defined in the tox.ini (default: docs/_build/html)
108     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
109     :project-pattern: Project to trigger build against. (default: \*\*)
110     :stream: Keyword representing a release code-name.
111         Often the same as the branch. (default: master)
112     :submodule-recursive: Whether to checkout submodules recursively.
113         (default: true)
114
115     :gerrit_verify_triggers: Override Gerrit Triggers.
116     :gerrit_trigger_file_paths: Override file paths filter which checks which
117         file modifications will trigger a build.
118         **default**::
119
120             - compare-type: ANT
121               pattern: '**/*.rst'
122             - compare-type: ANT
123               pattern: '**/conf.py'