docs/jjb/lf-rtdv3-jobs.rst

   1 .. _lf-global-jjb-rtdv3-jobs:
   2
   3 ##########################
   4 ReadTheDocs Version:3 Jobs
   5 ##########################
   6
   7 ReadTheDocs V3 jobs support documentation that is structured as a
   8 master documentation project plus a sub-project for each software
   9 component.  The master project files are usually maintained in a
  10 "docs" git repository and should contain an index with links to all
  11 the sub-projects. Each sub-project must maintain its documentation
  12 files in a "docs" subdirectory within that software component's git
  13 repository.
  14
  15 The RTDv3 Jenkins jobs publish documentation by triggering builds at
  16 ReadTheDocs.io. That build process clones the appropriate repository
  17 and transforms Real Simple Text (RST) and other files into HTML.
  18 Master project builds are performed separately from sub-project
  19 builds.
  20
  21 The ReadTheDocs site supports multiple versions of documentation for
  22 the master project and every sub-project.  Every project should have a
  23 development branch that's published at ReadTheDocs under the title
  24 "latest"; in git this is usually the "master" branch.  Most projects
  25 also declare releases periodically.  ReadTheDocs automatically detects
  26 the creation of git branches and git tags, and publishes the most
  27 recent one under the title "stable."  For more details please see
  28 `ReadTheDocs Versions
  29 <https://docs.readthedocs.io/en/stable/versions.html>`_.  Teams can
  30 control this process using Jenkins job configuration parameters as
  31 discussed below.
  32
  33 User setup
  34 ----------
  35
  36 To transform your rst documentation into a read the docs page, this job must be
  37 configured and created as described in Admin setup below. Once this is complete
  38 the following files must be added to your repository:
  39
  40 .. code-block:: bash
  41
  42    .readthedocs.yaml
  43    tox.ini
  44    docs
  45    docs/_static
  46    docs/_static/logo.png
  47    docs/conf.yaml
  48    docs/favicon.ico
  49    docs/index.rst
  50    docs/requirements-docs.txt
  51    docs/conf.py
  52
  53 Rather than have you copy and paste these files from a set of docs here, the
  54 following repo contains a script that will do this for you. Please refer to the
  55 explanation presented in: https://github.com/lfit-sandbox/test. This is all
  56 currently a beta feature, so feedback is encouraged. The script
  57 `docs_script.sh` is not needed, you can copy the files by hand if you prefer.
  58
  59 Once these files are correctly configured in your repository you can test
  60 locally:
  61
  62 .. code-block:: bash
  63
  64    tox -e docs,docs-linkcheck
  65
  66
  67 Stable Branch Instructions
  68 --------------------------
  69
  70 If your project does not create branches, you can skip this step.
  71 Once you branch your project modify your conf.yaml and add the following line:
  72
  73 .. code-block:: bash
  74
  75    version: 'ReleaseBranchName'
  76
  77 This will update the docs and change "master" on the top bar to your branch
  78 name. This change should be done against your release branch, this change will
  79 trigger a Read The Docs build which will create a new landing point for your
  80 documentation.
  81
  82 This landing point is called /stable/ and is selectable as a version in the
  83 bottom right corner of all Read The Docs pages.  Once all projects have
  84 branched and modified their conf.py they will have available their /stable/
  85 documentation. The process to release the documentation (that is to change the
  86 default landing point of your docs from /latest/ to /stable/) is to change the
  87 default-version in the jenkins job config as follows:
  88
  89 From:
  90
  91 .. code-block:: bash
  92
  93    default-version: latest
  94
  95 To:
  96
  97 .. code-block:: bash
  98
  99    default-version: ReleaseBranchName
 100
 101
 102 Admin setup:
 103
 104 This is a global job that only needs to be added once to your project's ci-mangement git
 105 repository. It leverages the read the docs v3 api to create projects on the fly, as well
 106 as setting up subproject associations with the master doc.
 107
 108 Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the
 109 root of the repository
 110
 111 The master doc must be defined in
 112 jenkins-config/global-vars-{production|sandbox}.sh
 113
 114 Normally this project is called doc or docs or documentation and all other docs build will
 115 be set as a subproject of this job.
 116
 117 examples:
 118
 119 .. code-block:: bash
 120
 121    global-vars-sandbox.sh:
 122    MASTER_RTD_PROJECT=doc-test
 123    global-vars-production.sh:
 124    MASTER_RTD_PROJECT=doc
 125
 126 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
 127 documentation.
 128
 129 Example job config:
 130
 131 example file: ci-management/jjb/rtd/rtd.yaml
 132
 133 .. code-block:: bash
 134
 135    ---
 136    - project:
 137        name: rtdv3-global-verify
 138        build-node: centos7-builder-1c-1g
 139        default-version: latest
 140        jobs:
 141          - rtdv3-global-verify
 142        stream:
 143          - master:
 144              branch: master
 145          - foo:
 146              branch: stable/{stream}
 147
 148    - project:
 149        name: rtdv3-global-merge
 150        default-version: latest
 151        build-node: centos7-builder-1c-1g
 152        jobs:
 153          - rtdv3-global-merge
 154        stream:
 155          - master:
 156              branch: master
 157          - foo:
 158              branch: stable/{stream}
 159
 160 Or add both jobs via a job group:
 161
 162
 163 .. code-block:: bash
 164
 165    ---
 166    - project:
 167        name: rtdv3-global
 168        default-version: latest
 169        build-node: centos7-builder-1c-1g
 170        jobs:
 171          - rtdv3-global
 172        stream:
 173          - master:
 174              branch: master
 175
 176
 177 Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
 178
 179 Job requires an lftools config section, this is to provide api access to read the docs.
 180
 181 .. code-block:: bash
 182
 183    [rtd]
 184    endpoint = https://readthedocs.org/api/v3/
 185    token = [hidden]
 186
 187 Merge Job will create a project on read the docs if none exist.
 188 Merge Job will assign a project as a subproject of the master project.
 189 Merge job will trigger a build to update docs.
 190 Merge job will change the default version if needed.
 191
 192 Macros
 193 ======
 194
 195 lf-rtdv3-common
 196 ---------------
 197
 198 RTD verify and merge jobs are the same except for their scm, trigger, and
 199 builders definition. This anchor is the common template.
 200
 201
 202 Job Templates
 203 =============
 204
 205 ReadTheDocs v3 Merge
 206 --------------------
 207
 208 Merge job which triggers a build of the docs to readthedocs.
 209
 210 :Template Names:
 211     - rtdv3-global-merge-{stream}
 212
 213 :Comment Trigger: remerge
 214
 215 :Required parameters:
 216
 217     :build-node: The node to run build on.
 218     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 219         in defaults.yaml)
 220
 221 :Optional parameters:
 222
 223     :branch: Git branch to fetch for the build. (default: master)
 224     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 225     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 226     :default-version: default page to redirect to for documentation (default /latest/)
 227     :disable-job: Whether to disable the job (default: false)
 228     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 229     :project-pattern: Project to trigger build against. (default: \*\*)
 230     :stream: Keyword representing a release code-name.
 231         Often the same as the branch. (default: master)
 232     :submodule-recursive: Whether to checkout submodules recursively.
 233         (default: true)
 234     :submodule-timeout: Timeout (in minutes) for checkout operation.
 235         (default: 10)
 236     :submodule-disable: Disable submodule checkout operation.
 237         (default: false)
 238
 239     :gerrit_merge_triggers: Override Gerrit Triggers.
 240     :gerrit_trigger_file_paths: Override file paths filter which checks which
 241         file modifications will trigger a build.
 242         **default**::
 243
 244             - compare-type: REG_EXP
 245               pattern: '^docs\/.*'
 246
 247
 248 ReadTheDocs v3 Verify
 249 ---------------------
 250
 251 Verify job which runs a tox build of the docs project.
 252 Also outputs some info on the build.
 253
 254 :Template Names:
 255     - rtdv3-global-verify-{stream}
 256
 257 :Comment Trigger: recheck|reverify
 258
 259 :Required Parameters:
 260
 261     :build-node: The node to run build on.
 262     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 263         in defaults.yaml)
 264
 265 :Optional Parameters:
 266
 267     :branch: Git branch to fetch for the build. (default: master)
 268     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 269     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 270     :gerrit-skip-vote: Skip voting for this job. (default: false)
 271     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 272     :disable-job: Whether to disable the job (default: false)
 273     :project-pattern: Project to trigger build against. (default: \*\*)
 274     :stream: Keyword representing a release code-name.
 275         Often the same as the branch. (default: master)
 276     :submodule-recursive: Whether to checkout submodules recursively.
 277         (default: true)
 278     :submodule-timeout: Timeout (in minutes) for checkout operation.
 279         (default: 10)
 280     :submodule-disable: Disable submodule checkout operation.
 281         (default: false)
 282
 283     :gerrit_verify_triggers: Override Gerrit Triggers.
 284     :gerrit_trigger_file_paths: Override file paths filter which checks which
 285         file modifications will trigger a build.
 286         **default**::
 287
 288             - compare-type: REG_EXP
 289               pattern: '^docs\/.*'