docs/jjb/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 To use this job first configure the ``Generic API incoming webhook`` in
  50 ReadTheDocs. To do that follow these steps:
  51
  52 #. Browse to https://readthedocs.org/dashboard/PROJECT/integrations/
  53 #. Click on ``Generic API incoming webhook``
  54
  55    .. note::
  56
  57       If not available click on ``Add integration`` and add the
  58       ``Generic API incoming webhook``.
  59
  60 #. Copy the custom webhook URL, this is your ``rtd-build-url``
  61
  62    For example: https://readthedocs.org/api/v2/webhook/opendaylight/32321/
  63
  64 #. Copy the token, this is your ``rtd-token``
  65
  66 :Template Names:
  67     - {project-name}-rtd-merge-{stream}
  68     - gerrit-rtd-merge
  69     - github-rtd-merge
  70
  71 :Comment Trigger: remerge
  72
  73 :Required parameters:
  74
  75     :build-node: The node to run build on.
  76     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
  77         in defaults.yaml)
  78     :rtd-build-url: This is the generic webhook url from readthedocs.org. Refer
  79         to the above instructions to generate one.
  80         (Check Admin > Integrations > Generic API incoming webhook)
  81     :rtd-token: The unique token for the project Generic webhook. Refer
  82         to the above instructions to generate one.
  83         (Check Admin > Integrations > Generic API incoming webhook)
  84
  85 :Optional parameters:
  86
  87     :branch: Git branch to fetch for the build. (default: master)
  88     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  89     :build-timeout: Timeout in minutes before aborting build. (default: 15)
  90     :git-url: base URL of git project. (default: https://github.com)
  91     :project-pattern: Project to trigger build against. (default: \*\*)
  92     :stream: Keyword representing a release code-name.
  93         Often the same as the branch. (default: master)
  94     :submodule-recursive: Whether to checkout submodules recursively.
  95         (default: true)
  96
  97     :gerrit_merge_triggers: Override Gerrit Triggers.
  98     :gerrit_trigger_file_paths: Override file paths filter which checks which
  99         file modifications will trigger a build.
 100         **default**::
 101
 102             - compare-type: ANT
 103               pattern: '**/*.rst'
 104             - compare-type: ANT
 105               pattern: '**/conf.py'
 106
 107
 108 ReadTheDocs Verify
 109 ------------------
 110
 111 Verify job which runs a tox build of the docs project
 112
 113 :Template Names:
 114     - {project-name}-rtd-verify-{stream}
 115     - gerrit-rtd-verify
 116     - github-rtd-verify
 117
 118 :Comment Trigger: recheck|reverify
 119
 120 :Required Parameters:
 121
 122     :build-node: The node to run build on.
 123     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 124         in defaults.yaml)
 125
 126 :Optional Parameters:
 127
 128     :branch: Git branch to fetch for the build. (default: master)
 129     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 130     :build-node: The node to run build on.
 131     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 132     :doc-dir: Directory where tox will place built docs.
 133         as defined in the tox.ini (default: docs/_build/html)
 134     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 135     :project-pattern: Project to trigger build against. (default: \*\*)
 136     :stream: Keyword representing a release code-name.
 137         Often the same as the branch. (default: master)
 138     :submodule-recursive: Whether to checkout submodules recursively.
 139         (default: true)
 140
 141     :gerrit_verify_triggers: Override Gerrit Triggers.
 142     :gerrit_trigger_file_paths: Override file paths filter which checks which
 143         file modifications will trigger a build.
 144         **default**::
 145
 146             - compare-type: ANT
 147               pattern: '**/*.rst'
 148             - compare-type: ANT
 149               pattern: '**/conf.py'