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.  There is some setup
  48 required on read the docs to get started with this.  After you have created the
  49 individual read the docs project (lets call it "PROJECT" here), then browse to
  50 https://readthedocs.org/dashboard/PROJECT/integrations/ and click on
  51 "Generic API incoming webhook".  Here you will see a custom url to trigger the job as
  52 well as a token.  Persist the token in the project Jenkins global-settings
  53 file.  You will need to put it in a username/password credentials type to make
  54 it available in the global-settings file.  set ```rtd-build-url to the
  55 custom build url as defined in read the docs.  Also set the rtd-server-id
  56 to the id you specified in the global-settings file, this will enable the script to parse
  57 the token out. Set ```rtd-project``` to your read the docs project name.
  58
  59
  60 :Template Names:
  61     - {project-name}-rtd-merge-{stream}
  62     - gerrit-rtd-merge
  63     - github-rtd-merge
  64
  65 :Required parameters:
  66
  67     :build-node: The node to run build on.
  68     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
  69         in defaults.yaml)
  70     :rtd-project: This is the name of the project on ReadTheDocs.org.
  71     :rtd-build-url: This is the generic webhook url from readthedocs.org
  72     :global-settings-file: This is the location of the Jenkins global settings file.
  73         This file contains the entry with the location for the readthedocs build token.
  74     :rtd-server-id: This is the id of the entry in the global-settings-file.
  75
  76
  77 :Optional parameters:
  78
  79     :branch: Git branch to fetch for the build. (default: master)
  80     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  81     :build-timeout: Timeout in seconds before aborting build. (default: 15)
  82     :git-url: base URL of git project. (default: https://github.com)
  83     :project-pattern: Project to trigger build against. (default: \*\*)
  84     :stream: Keyword representing a release code-name.
  85         Often the same as the branch. (default: master)
  86     :submodule-recursive: Whether to checkout submodules recursively.
  87         (default: true)
  88
  89     :gerrit_merge_triggers: Override Gerrit Triggers.
  90     :gerrit_trigger_file_paths: Override file paths filter which checks which
  91         file modifications will trigger a build.
  92         **default**::
  93
  94             - compare-type: ANT
  95               pattern: '**/*.rst'
  96             - compare-type: ANT
  97               pattern: '**/conf.py'
  98
  99
 100 ReadTheDocs Verify
 101 ------------------
 102
 103 Verify job which runs a tox build of the docs project
 104
 105 :Template Names:
 106     - {project-name}-rtd-verify-{stream}
 107     - gerrit-rtd-verify
 108     - github-rtd-verify
 109
 110 :Required Parameters:
 111
 112     :build-node: The node to run build on.
 113     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 114         in defaults.yaml)
 115
 116 :Optional Parameters:
 117
 118     :branch: Git branch to fetch for the build. (default: master)
 119     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 120     :build-node: The node to run build on.
 121     :build-timeout: Timeout in seconds before aborting build. (default: 15)
 122     :doc-dir: Directory where tox will place built docs.
 123         as defined in the tox.ini (default: docs/_build/html)
 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
 131     :gerrit_verify_triggers: Override Gerrit Triggers.
 132     :gerrit_trigger_file_paths: Override file paths filter which checks which
 133         file modifications will trigger a build.
 134         **default**::
 135
 136             - compare-type: ANT
 137               pattern: '**/*.rst'
 138             - compare-type: ANT
 139               pattern: '**/conf.py'