docs/jjb/lf-rtdv2-jobs.rst

   1 .. _lf-global-jjb-rtdv2-jobs:
   2
   3 ##########################
   4 ReadTheDocs Version:2 Jobs
   5 ##########################
   6
   7 This is a global job that only needs to be added once to your project's ci-mangement git repository. It leverages the read the docs v3 api to create projects on the fly, as well as set up subproject associations with the master doc.
   8
   9 The master doc must be defined in
  10 jenkins-config/global-vars-{production|sandbox}.sh
  11
  12 examples:
  13 global-vars-sandbox.sh:
  14 MASTER_RTD_PROJECT=doc-test
  15 global-vars-production.sh:
  16 MASTER_RTD_PROJECT=doc
  17
  18 In this way sandbox jobs will create docs with a test suffix and will not stomp on production documentation.
  19
  20 Example job config:
  21
  22 example file: ci-management/jjb/rtd/rtd.yaml
  23
  24 .. code-block:: bash
  25
  26     ---
  27     - project:
  28         name: rtdv2-verify-global
  29         build-node: centos7-builder-1c-1g
  30         jobs:
  31           - rtdv2-verify-global
  32         stream:
  33           - master:
  34               branch: master
  35           - foo:
  36               branch: stable/{stream}
  37
  38     - project:
  39         name: rtdv2-merge-global
  40         build-node: centos7-builder-1c-1g
  41         jobs:
  42           - rtdv2-merge-global
  43         stream:
  44           - master:
  45               branch: master
  46           - foo:
  47               branch: stable/{stream}
  48
  49 Or add both jobs via a job group:
  50
  51
  52 .. code-block:: bash
  53
  54     ---
  55     - project:
  56         name: rtdv2-global
  57         build-node: centos7-builder-1c-1g
  58         jobs:
  59           - rtdv2-global
  60         stream:
  61           - master:
  62               branch: master
  63
  64
  65 Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
  66
  67 Job requires an lftools config section, this is to provide api access to read the docs.
  68
  69 .. code-block:: bash
  70
  71     [rtd]
  72     endpoint = https://readthedocs.org/api/v3/
  73     token = [hidden]
  74
  75 Merge Job will create a project on read the docs if none exist.
  76 Merge Job will assign a project as a subproject of the master project.
  77 Merge job will trigger a build to update docs.
  78
  79 Macros
  80 ======
  81
  82 lf-rtdv2-common
  83 ---------------
  84
  85 RTD verify and merge jobs are the same except for their scm, trigger, and
  86 builders definition. This anchor is the common template.
  87
  88
  89 Job Templates
  90 =============
  91
  92 ReadTheDocs v2 Merge
  93 --------------------
  94
  95 Merge job which triggers a build of the docs to readthedocs.
  96
  97 :Template Names:
  98     - rtdv2-merge-global-{stream}
  99
 100 :Comment Trigger: remerge
 101
 102 :Required parameters:
 103
 104     :build-node: The node to run build on.
 105     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 106         in defaults.yaml)
 107
 108 :Optional parameters:
 109
 110     :branch: Git branch to fetch for the build. (default: master)
 111     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 112     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 113     :project-pattern: Project to trigger build against. (default: \*\*)
 114     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 115     :disable-job: Whether to disable the job (default: false)
 116     :stream: Keyword representing a release code-name.
 117         Often the same as the branch. (default: master)
 118     :submodule-recursive: Whether to checkout submodules recursively.
 119         (default: true)
 120     :submodule-timeout: Timeout (in minutes) for checkout operation.
 121         (default: 10)
 122     :submodule-disable: Disable submodule checkout operation.
 123         (default: false)
 124
 125     :gerrit_merge_triggers: Override Gerrit Triggers.
 126     :gerrit_trigger_file_paths: Override file paths filter which checks which
 127         file modifications will trigger a build.
 128         **default**::
 129
 130             - compare-type: REG_EXP
 131               pattern: '.*\.css'
 132             - compare-type: REG_EXP
 133               pattern: '.*\.html'
 134             - compare-type: REG_EXP
 135               pattern: '.*\.rst'
 136             - compare-type: REG_EXP
 137               pattern: '.*\/conf.py'
 138
 139
 140
 141 ReadTheDocs v2 Verify
 142 ---------------------
 143
 144 Verify job which runs a tox build of the docs project.
 145 Also outputs some info on the build
 146
 147 :Template Names:
 148     - rtdv2-verify-global-{stream}
 149
 150 :Comment Trigger: recheck|reverify
 151
 152 :Required Parameters:
 153
 154     :build-node: The node to run build on.
 155     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 156         in defaults.yaml)
 157
 158 :Optional Parameters:
 159
 160     :branch: Git branch to fetch for the build. (default: master)
 161     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 162     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 163     :gerrit-skip-vote: Skip voting for this job. (default: false)
 164     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 165     :disable-job: Whether to disable the job (default: false)
 166     :project-pattern: Project to trigger build against. (default: \*\*)
 167     :stream: Keyword representing a release code-name.
 168         Often the same as the branch. (default: master)
 169     :submodule-recursive: Whether to checkout submodules recursively.
 170         (default: true)
 171     :submodule-timeout: Timeout (in minutes) for checkout operation.
 172         (default: 10)
 173     :submodule-disable: Disable submodule checkout operation.
 174         (default: false)
 175
 176     :gerrit_verify_triggers: Override Gerrit Triggers.
 177     :gerrit_trigger_file_paths: Override file paths filter which checks which
 178         file modifications will trigger a build.
 179         **default**::
 180
 181             - compare-type: REG_EXP
 182               pattern: '.*\.css'
 183             - compare-type: REG_EXP
 184               pattern: '.*\.html'
 185             - compare-type: REG_EXP
 186               pattern: '.*\.rst'
 187             - compare-type: REG_EXP
 188               pattern: '.*\/conf.py'