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