docs/jjb/lf-rtd-jobs.rst

   1 ################
   2 ReadTheDocs Jobs
   3 ################
   4
   5 Job Groups
   6 ==========
   7
   8 {project-name}-rtd-jobs
   9 ----------------------
  10
  11 Jobs that should be deployed for a project producing ReadTheDocs using Gerrit.
  12
  13 :Includes:
  14
  15     - gerrit-rtd-merge
  16     - gerrit-rtd-verify
  17
  18 {project-name}-github-rtd-jobs
  19 -----------------------------
  20
  21 Jobs that should be deployed for a project producing ReadTheDocs using GitHub.
  22
  23 :Includes:
  24
  25     - github-rtd-merge
  26     - github-rtd-verify
  27
  28
  29 Macros
  30 ======
  31
  32 lf-rtd-common
  33 -------------
  34
  35 RTD verify and merge jobs are the same except for their scm, trigger, and
  36 builders definition. This anchor is the common template.
  37
  38
  39 Job Templates
  40 =============
  41
  42 ReadTheDocs Merge
  43 -----------------
  44
  45 Merge job which triggers a POST of the docs project to readthedocs
  46
  47 :Template Names:
  48     - {project-name}-rtd-merge-{stream}
  49     - gerrit-rtd-merge
  50     - github-rtd-merge
  51
  52 :Required parameters:
  53
  54     :build-node: The node to run build on.
  55     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  56         be configured in defaults.yaml)
  57     :rtd-project: This is the name of the project on ReadTheDocs.org.
  58
  59 :Optional parameters:
  60
  61     :branch: Git branch to fetch for the build. (default: master)
  62     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  63     :build-timeout: Timeout in seconds before aborting build. (default: 15)
  64     :git-url: base URL of git project. (default: https://github.com)
  65     :project-pattern: Project to trigger build against. (default: **)
  66     :stream: Keyword that can be used to represent a release code-name.
  67         Often the same as the branch. (default: master)
  68     :submodule-recursive: Whether to checkout submodules recursively.
  69         (default: true)
  70
  71     :gerrit_merge_triggers: Override Gerrit Triggers.
  72     :gerrit_trigger_file_paths: Override file paths which can be used to
  73         filter which file modifications will trigger a build.
  74         **default**::
  75
  76             - compare-type: ANT
  77               pattern: '**/*.rst'
  78             - compare-type: ANT
  79               pattern: '**/conf.py'
  80
  81
  82 ReadTheDocs Verify
  83 ------------------
  84
  85 Verify job which runs a tox build of the docs project
  86
  87 :Template Names:
  88     - {project-name}-rtd-verify-{stream}
  89     - gerrit-rtd-verify
  90     - github-rtd-verify
  91
  92 :Required Parameters:
  93
  94     :build-node: The node to run build on.
  95     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  96         be configured in defaults.yaml)
  97
  98 :Optional Parameters:
  99
 100     :branch: Git branch to fetch for the build. (default: master)
 101     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 102     :build-node: The node to run build on.
 103     :build-timeout: Timeout in seconds before aborting build. (default: 15)
 104     :doc-dir: Directory where tox will place built docs.
 105         as defined in the tox.ini (default: docs/_build/html)
 106     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 107     :project-pattern: Project to trigger build against. (default: **)
 108     :stream: Keyword that can be used to represent a release code-name.
 109         Often the same as the branch. (default: master)
 110     :submodule-recursive: Whether to checkout submodules recursively.
 111         (default: true)
 112
 113     :gerrit_verify_triggers: Override Gerrit Triggers.
 114     :gerrit_trigger_file_paths: Override file paths which can be used to
 115         filter which file modifications will trigger a build.
 116         **default**::
 117
 118             - compare-type: ANT
 119               pattern: '**/*.rst'
 120             - compare-type: ANT
 121               pattern: '**/conf.py'