c5c9172f6e7787f472527508ed75b5df45f2b813
[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 .. include:: ../job-groups.rst
11
12 Below is a list of Maven job groups:
13
14 .. literalinclude:: ../../jjb/lf-rtd-job-groups.yaml
15    :language: yaml
16
17
18 Macros
19 ======
20
21 lf-rtd-common
22 -------------
23
24 RTD verify and merge jobs are the same except for their scm, trigger, and
25 builders definition. This anchor is the common template.
26
27
28 Job Templates
29 =============
30
31 ReadTheDocs Merge
32 -----------------
33
34 Merge job which triggers a POST of the docs project to readthedocs.
35
36 To use this job first configure the ``Generic API incoming webhook`` in
37 ReadTheDocs. To do that follow these steps:
38
39 #. Browse to https://readthedocs.org/dashboard/PROJECT/integrations/
40 #. Click on ``Generic API incoming webhook``
41
42    .. note::
43
44       If not available click on ``Add integration`` and add the
45       ``Generic API incoming webhook``.
46
47 #. Copy the custom webhook URL, this is your ``rtd-build-url``
48
49    For example: https://readthedocs.org/api/v2/webhook/opendaylight/32321/
50
51 #. Copy the token, this is your ``rtd-token``
52
53 :Template Names:
54     - {project-name}-rtd-merge-{stream}
55     - gerrit-rtd-merge
56     - github-rtd-merge
57
58 :Comment Trigger: remerge
59
60 :Required parameters:
61
62     :build-node: The node to run build on.
63     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
64         in defaults.yaml)
65     :rtd-build-url: This is the generic webhook url from readthedocs.org. Refer
66         to the above instructions to generate one.
67         (Check Admin > Integrations > Generic API incoming webhook)
68     :rtd-token: The unique token for the project Generic webhook. Refer
69         to the above instructions to generate one.
70         (Check Admin > Integrations > Generic API incoming webhook)
71
72 :Optional parameters:
73
74     :branch: Git branch to fetch for the build. (default: master)
75     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
76     :build-timeout: Timeout in minutes before aborting build. (default: 15)
77     :git-url: base URL of git project. (default: https://github.com)
78     :project-pattern: Project to trigger build against. (default: \*\*)
79     :stream: Keyword representing a release code-name.
80         Often the same as the branch. (default: master)
81     :submodule-recursive: Whether to checkout submodules recursively.
82         (default: true)
83     :submodule-timeout: Timeout (in minutes) for checkout operation.
84         (default: 10)
85
86     :gerrit_merge_triggers: Override Gerrit Triggers.
87     :gerrit_trigger_file_paths: Override file paths filter which checks which
88         file modifications will trigger a build.
89         **default**::
90
91             - compare-type: ANT
92               pattern: '**/*.rst'
93             - compare-type: ANT
94               pattern: '**/conf.py'
95
96
97 ReadTheDocs Verify
98 ------------------
99
100 Verify job which runs a tox build of the docs project
101
102 :Template Names:
103     - {project-name}-rtd-verify-{stream}
104     - gerrit-rtd-verify
105     - github-rtd-verify
106
107 :Comment Trigger: recheck|reverify
108
109 :Required Parameters:
110
111     :build-node: The node to run build on.
112     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
113         in defaults.yaml)
114
115 :Optional Parameters:
116
117     :branch: Git branch to fetch for the build. (default: master)
118     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
119     :build-node: The node to run build on.
120     :build-timeout: Timeout in minutes before aborting build. (default: 15)
121     :doc-dir: Directory where tox will place built docs.
122         as defined in the tox.ini (default: docs/_build/html)
123     :gerrit-skip-vote: Skip voting for this job. (default: false)
124     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
125     :project-pattern: Project to trigger build against. (default: \*\*)
126     :stream: Keyword representing a release code-name.
127         Often the same as the branch. (default: master)
128     :submodule-recursive: Whether to checkout submodules recursively.
129         (default: true)
130     :submodule-timeout: Timeout (in minutes) for checkout operation.
131         (default: 10)
132
133     :gerrit_verify_triggers: Override Gerrit Triggers.
134     :gerrit_trigger_file_paths: Override file paths filter which checks which
135         file modifications will trigger a build.
136         **default**::
137
138             - compare-type: ANT
139               pattern: '**/*.rst'
140             - compare-type: ANT
141               pattern: '**/conf.py'