docs/jjb/lf-rtdv3-jobs.rst

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