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 .. 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     :submodule-disable: Disable submodule checkout operation.
  86         (default: false)
  87
  88     :gerrit_merge_triggers: Override Gerrit Triggers.
  89     :gerrit_trigger_file_paths: Override file paths filter which checks which
  90         file modifications will trigger a build.
  91         **default**::
  92
  93             - compare-type: ANT
  94               pattern: '**/*.rst'
  95             - compare-type: ANT
  96               pattern: '**/conf.py'
  97
  98
  99 ReadTheDocs Verify
 100 ------------------
 101
 102 Verify job which runs tox to test the docs project
 103
 104 :Template Names:
 105     - {project-name}-rtd-verify-{stream}
 106     - gerrit-rtd-verify
 107     - github-rtd-verify
 108
 109 :Comment Trigger: recheck|reverify
 110
 111 :Required Parameters:
 112
 113     :build-node: The node to run build on.
 114     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 115         in defaults.yaml)
 116
 117 :Optional Parameters:
 118
 119     :branch: Git branch to fetch for the build. (default: master)
 120     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 121     :build-node: The node to run build on.
 122     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 123     :doc-dir: Directory where tox will place built docs.
 124         as defined in the tox.ini (default: docs/_build/html)
 125     :gerrit-skip-vote: Skip voting for this job. (default: false)
 126     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 127     :project-pattern: Project to trigger build against. (default: \*\*)
 128     :python-version: Python version (default: python2)
 129     :stream: Keyword representing a release code-name.
 130         Often the same as the branch. (default: master)
 131     :submodule-recursive: Whether to checkout submodules recursively.
 132         (default: true)
 133     :submodule-timeout: Timeout (in minutes) for checkout operation.
 134         (default: 10)
 135     :submodule-disable: Disable submodule checkout operation.
 136         (default: false)
 137
 138     :gerrit_verify_triggers: Override Gerrit Triggers.
 139     :gerrit_trigger_file_paths: Override file paths filter which checks which
 140         file modifications will trigger a build.
 141         **default**::
 142
 143             - compare-type: ANT
 144               pattern: '**/*.rst'
 145             - compare-type: ANT
 146               pattern: '**/conf.py'