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 :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'