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 The default location of the tox.ini file is in the git repository root
  60 directory. Optionally your documentation lead may decide to store all tox files
  61 within the required "docs" subdirectory by setting configuration option
  62 "tox-dir" to value "docs/" as discussed below.
  63
  64 If your project's tox dir is "docs/" and not "." the tox.ini must be
  65 reconfigured with the correct relative paths.
  66
  67 Once these files are correctly configured in your repository you can test
  68 locally:
  69
  70 .. code-block:: bash
  71
  72    tox -e docs,docs-linkcheck
  73
  74
  75 Stable Branch Instructions
  76 --------------------------
  77
  78 If your project does not create branches, you can skip this step.
  79 Once you branch your project modify your conf.yaml and add the following line:
  80
  81 .. code-block:: bash
  82
  83    version: 'ReleaseBranchName'
  84
  85 This will update the docs and change "master" on the top bar to your branch
  86 name. This change should be done against your release branch, this change will
  87 trigger a Read The Docs build which will create a new landing point for your
  88 documentation.
  89
  90 This landing point is called /stable/ and is selectable as a version in the
  91 bottom right corner of all Read The Docs pages.  Once all projects have
  92 branched and modified their conf.py they will have available their /stable/
  93 documentation. The process to release the documentation (that is to change the
  94 default landing point of your docs from /latest/ to /stable/) is to change the
  95 default-version in the jenkins job config as follows:
  96
  97 From:
  98
  99 .. code-block:: bash
 100
 101    default-version: latest
 102
 103 To:
 104
 105 .. code-block:: bash
 106
 107    default-version: ReleaseBranchName
 108
 109
 110 Admin setup:
 111
 112 This is a global job that only needs to be added once to your project's ci-mangement git
 113 repository. It leverages the read the docs v3 api to create projects on the fly, as well
 114 as setting up subproject associations with the master doc.
 115
 116 Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the
 117 root of the repository
 118
 119 The master doc must be defined in
 120 jenkins-config/global-vars-{production|sandbox}.sh
 121
 122 Normally this project is called doc or docs or documentation and all other docs build will
 123 be set as a subproject of this job.
 124
 125 examples:
 126
 127 .. code-block:: bash
 128
 129    global-vars-sandbox.sh:
 130    MASTER_RTD_PROJECT=doc-test
 131    global-vars-production.sh:
 132    MASTER_RTD_PROJECT=doc
 133
 134 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
 135 documentation.
 136
 137 Example job config:
 138
 139 example file: ci-management/jjb/rtd/rtd.yaml
 140
 141 .. code-block:: bash
 142
 143    ---
 144    - project:
 145        name: rtdv3-global-verify
 146        build-node: centos7-builder-1c-1g
 147        default-version: latest
 148        tox-dir: "."
 149        jobs:
 150          - rtdv3-global-verify
 151        stream:
 152          - master:
 153              branch: master
 154          - foo:
 155              branch: stable/{stream}
 156
 157    - project:
 158        name: rtdv3-global-merge
 159        default-version: latest
 160        build-node: centos7-builder-1c-1g
 161        jobs:
 162          - rtdv3-global-merge
 163        stream:
 164          - master:
 165              branch: master
 166          - foo:
 167              branch: stable/{stream}
 168
 169 Or add both jobs via a job group:
 170
 171
 172 .. code-block:: bash
 173
 174    ---
 175    - project:
 176        name: rtdv3-global
 177        default-version: latest
 178        tox-dir: "."
 179        build-node: centos7-builder-1c-1g
 180        jobs:
 181          - rtdv3-global
 182        stream:
 183          - master:
 184              branch: master
 185
 186
 187 Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
 188
 189 Job requires an lftools config section, this is to provide api access to read the docs.
 190
 191 .. code-block:: bash
 192
 193    [rtd]
 194    endpoint = https://readthedocs.org/api/v3/
 195    token = [hidden]
 196
 197 Merge Job will create a project on read the docs if none exist.
 198 Merge Job will assign a project as a subproject of the master project.
 199 Merge job will trigger a build to update docs.
 200 Merge job will change the default version if needed.
 201
 202 Macros
 203 ======
 204
 205 lf-rtdv3-common
 206 ---------------
 207
 208 RTD verify and merge jobs are the same except for their scm, trigger, and
 209 builders definition. This anchor is the common template.
 210
 211
 212 Job Templates
 213 =============
 214
 215 ReadTheDocs v3 Merge
 216 --------------------
 217
 218 Merge job which triggers a build of the docs to readthedocs.
 219
 220 :Template Names:
 221     - rtdv3-global-merge-{stream}
 222
 223 :Comment Trigger: remerge
 224
 225 :Required parameters:
 226
 227     :build-node: The node to run build on.
 228     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 229         in defaults.yaml)
 230
 231 :Optional parameters:
 232
 233     :branch: Git branch to fetch for the build. (default: master)
 234     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 235     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 236     :default-version: default page to redirect to for documentation (default /latest/)
 237     :disable-job: Whether to disable the job (default: false)
 238     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 239     :project-pattern: Project to trigger build against. (default: \*\*)
 240     :stream: Keyword representing a release code-name.
 241         Often the same as the branch. (default: master)
 242     :submodule-recursive: Whether to checkout submodules recursively.
 243         (default: true)
 244     :submodule-timeout: Timeout (in minutes) for checkout operation.
 245         (default: 10)
 246     :submodule-disable: Disable submodule checkout operation.
 247         (default: false)
 248
 249     :gerrit_merge_triggers: Override Gerrit Triggers.
 250     :gerrit_trigger_file_paths: Override file paths filter which checks which
 251         file modifications will trigger a build.
 252         **default**::
 253
 254             - compare-type: REG_EXP
 255               pattern: '^docs\/.*'
 256
 257
 258 ReadTheDocs v3 Verify
 259 ---------------------
 260
 261 Verify job which runs a tox build of the docs project.
 262 Also outputs some info on the build.
 263
 264 :Template Names:
 265     - rtdv3-global-verify-{stream}
 266
 267 :Comment Trigger: recheck|reverify
 268
 269 :Required Parameters:
 270
 271     :build-node: The node to run build on.
 272     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 273         in defaults.yaml)
 274
 275 :Optional Parameters:
 276
 277     :branch: Git branch to fetch for the build. (default: master)
 278     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 279     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 280     :gerrit-skip-vote: Skip voting for this job. (default: false)
 281     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 282     :disable-job: Whether to disable the job (default: false)
 283     :project-pattern: Project to trigger build against. (default: \*\*)
 284     :stream: Keyword representing a release code-name.
 285         Often the same as the branch. (default: master)
 286     :submodule-recursive: Whether to checkout submodules recursively.
 287         (default: true)
 288     :submodule-timeout: Timeout (in minutes) for checkout operation.
 289         (default: 10)
 290     :submodule-disable: Disable submodule checkout operation.
 291         (default: false)
 292     :tox-dir: Directory containing the project's read the docs tox.ini
 293     :gerrit_verify_triggers: Override Gerrit Triggers.
 294     :gerrit_trigger_file_paths: Override file paths filter which checks which
 295         file modifications will trigger a build.
 296         **default**::
 297
 298             - compare-type: REG_EXP
 299               pattern: '^docs\/.*'