docs/jjb/lf-rtdv3-jobs.rst

   1 .. _lf-global-jjb-rtdv3-jobs:
   2
   3 ##########################
   4 ReadTheDocs Version:3 Jobs
   5 ##########################
   6
   7 ReadTheDocs supports the nesting of projects, by configuring a project as a
   8 subproject of another project. This allows for documentation projects to share
   9 a search index and a namespace or custom domain, while still maintained
  10 independently of each other.
  11
  12 The master Read The Docs project files, maintained in a "docs" Git repository
  13 should contain an index with links to all the sub-projects. Each sub-project
  14 must maintain its documentation files in a "docs" subdirectory within that
  15 software component's Git repository.
  16
  17 The RTDv3 Jenkins jobs publish documentation by triggering builds at
  18 ReadTheDocs.io. That build process clones the appropriate repository
  19 and transforms reStructuredText (RST) and other files into HTML.
  20 All project's Read the Docs builds separately from sub-project builds.
  21
  22 The Read The Docs site supports versioned documentation for the master project
  23 and every sub-project.  Every project should have a development branch that's
  24 published at ReadTheDocs under the title "latest"; in Git this is the "master"
  25 branch although can be different in some projects.  Most projects also declare
  26 releases periodically.  ReadTheDocs automatically detects the creation of git
  27 branches and git tags, and publishes the most recent one under the title
  28 "stable."  For more details please see `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, configure as
  37 described in Admin setup below. Once this is complete, add the following files
  38 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 copying and pasting 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 a
  56 beta feature, so please send feedback on your experiences. Once complete, the
  57 script ``docs_script.sh`` is not needed. You can copy the files by hand if you
  58 prefer.
  59
  60 The default location of the tox.ini file is in the git repository root
  61 directory. Optionally your documentation lead may decide to store all tox files
  62 within the required "docs" subdirectory by setting configuration option
  63 "tox-dir" to value "docs/" as discussed below.
  64
  65 If your project's tox dir is ``docs/`` and not ``.``, update the tox.ini
  66 configuration with the correct relative paths.
  67
  68 You must also set the doc-dir. For example, from the default of
  69 ``doc-dir: "docs/_build/html"`` to ``doc-dir: "_build/html"``, as the relative
  70 path in the tox run has changed.
  71
  72 Once configured, in your repository you can build the rst files locally to
  73 test:
  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
  85 For Read The Docs to see your new branch, trigger a build to force RTD to run
  86 an update. Use a trivial change to any file in your project's ``/docs/``
  87 directory on your newly minted branch to trigger a build and activate your
  88 project's new branch on Read The Docs. This will create a new selectable
  89 version in the bottom right corner of your project's Read The Docs page.
  90 Once all projects have branched the process to release the documentation
  91 (that is to change the default landing point of your docs from /latest/ to /branchname/)
  92 is to change the default-version in the jenkins job config as follows:
  93
  94 From:
  95
  96 .. code-block:: bash
  97
  98    default-version: latest
  99
 100 To:
 101
 102 .. code-block:: bash
 103
 104    default-version: ReleaseBranchName
 105
 106
 107 Admin setup:
 108 ------------
 109
 110 This part of the documentation explains how to enable this job so that It will trigger
 111 on docs/* changes for all projects in a Gerrit instance. It leverages the
 112 Read The Docs v3 api to create projects on the fly, as well as setting up
 113 sub-project associations with the master doc.
 114
 115 A ``.readthedocs.yaml`` must exist in the root of the repository otherwise the
 116 jobs will run but skip actual verification.
 117
 118 Define the master doc in jenkins-config/global-vars-{production|sandbox}.sh
 119
 120 This project named "doc" or "docs" or "documentation" will set all other docs
 121 builds as a subproject of this job.
 122
 123 examples:
 124
 125 .. code-block:: bash
 126
 127    global-vars-sandbox.sh:
 128    MASTER_RTD_PROJECT=doc-test
 129    global-vars-production.sh:
 130    MASTER_RTD_PROJECT=doc
 131
 132 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
 133 documentation.
 134
 135 Example job config:
 136
 137 example file: ci-management/jjb/rtd/rtd.yaml
 138
 139 .. code-block:: bash
 140
 141    ---
 142    - project:
 143        name: rtdv3-global-verify
 144        build-node: centos7-builder-1c-1g
 145        default-version: latest
 146        tox-dir: "."
 147        doc-dir: "docs/_build/html"
 148        jobs:
 149          - rtdv3-global-verify
 150        stream:
 151          - master:
 152              branch: master
 153          - foo:
 154              branch: stable/{stream}
 155
 156    - project:
 157        name: rtdv3-global-merge
 158        default-version: latest
 159        tox-dir: "."
 160        doc-dir: "docs/_build/html"
 161        build-node: centos7-builder-1c-1g
 162        jobs:
 163          - rtdv3-global-merge
 164        stream:
 165          - master:
 166              branch: master
 167          - foo:
 168              branch: stable/{stream}
 169
 170 Or add both jobs via a job group:
 171 This real-world example also shows how to configure your builds to use
 172 a tox.ini that lived inside your docs/ dir
 173
 174
 175 .. code-block:: bash
 176
 177    # Global read the docs version 3 jobs
 178    #
 179    # jobs trigger for all projects, all branches
 180    # on any changes to files in a docs/ directory
 181    # and publish subprojects to readthedocs.io
 182    # using credentials from Jenkins settings
 183    ---
 184    - project:
 185        name: rtdv3-view
 186        project-name: rtdv3-global
 187        views:
 188          - project-view
 189
 190    - project:
 191        name: rtdv3-global
 192        default-version: latest
 193        tox-dir: "docs/"
 194        doc-dir: "_build/html"
 195        build-node: centos7-builder-2c-1g
 196        # override the default to ignore ref-updated-event (tag)
 197        gerrit_merge_triggers:
 198          - change-merged-event
 199          - comment-added-contains-event:
 200              comment-contains-value: remerge$
 201        jobs:
 202          - rtdv3-global-verify
 203          - rtdv3-global-merge
 204        stream:
 205          - master:
 206              branch: '*'
 207
 208 GitHub jobs must be per-project. Once proven, a different set of jobs will be available.
 209
 210 Job requires an lftools config section, this is to provide api access to read the docs.
 211
 212 .. code-block:: bash
 213
 214    [rtd]
 215    endpoint = https://readthedocs.org/api/v3/
 216    token = [hidden]
 217
 218 Merge Job will create a project on Read The Docs if none exist.
 219 Merge Job will assign a project as a subproject of the master project.
 220 Merge job will trigger a build to update docs.
 221 Merge job will change the default version if needed.
 222
 223 Macros
 224 ======
 225
 226 lf-rtdv3-common
 227 ---------------
 228
 229 RTD verify and merge jobs are the same except for their scm, trigger, and
 230 builders definition. This anchor is the common template.
 231
 232
 233 Job Templates
 234 =============
 235
 236 ReadTheDocs v3 Merge
 237 --------------------
 238
 239 Merge job which triggers a build of the docs to Read The Docs.
 240
 241 :Template Names:
 242     - rtdv3-global-merge-{stream}
 243
 244 :Comment Trigger: remerge
 245
 246 :Required parameters:
 247
 248     :build-node: The node to run build on.
 249     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 250         in defaults.yaml)
 251
 252 :Optional parameters:
 253
 254     :branch: Git branch to fetch for the build. (default: master)
 255     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 256     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 257     :default-version: default page to redirect to for documentation (default /latest/)
 258     :disable-job: Whether to disable the job (default: false)
 259     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 260     :project-pattern: Project to trigger build against. (default: \*\*)
 261     :stream: Keyword representing a release code-name.
 262         Often the same as the branch. (default: master)
 263     :submodule-recursive: Whether to checkout submodules recursively.
 264         (default: true)
 265     :submodule-timeout: Timeout (in minutes) for checkout operation.
 266         (default: 10)
 267     :submodule-disable: Disable submodule checkout operation.
 268         (default: false)
 269     :tox-dir: Directory containing the project's Read The Docs tox.ini
 270     :doc-dir: Relative directory project's docs generated by tox
 271     :gerrit_merge_triggers: Override Gerrit Triggers.
 272     :gerrit_trigger_file_paths: Override file paths filter which checks which
 273         file modifications will trigger a build.
 274         **default**::
 275
 276             - compare-type: REG_EXP
 277               pattern: '^docs\/.*'
 278
 279
 280 ReadTheDocs v3 Verify
 281 ---------------------
 282
 283 Verify job which runs a tox build of the docs project.
 284 Also outputs some info on the build.
 285
 286 :Template Names:
 287     - rtdv3-global-verify-{stream}
 288
 289 :Comment Trigger: recheck|reverify
 290
 291 :Required Parameters:
 292
 293     :build-node: The node to run build on.
 294     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 295         in defaults.yaml)
 296
 297 :Optional Parameters:
 298
 299     :branch: Git branch to fetch for the build. (default: master)
 300     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 301     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 302     :gerrit-skip-vote: Skip voting for this job. (default: false)
 303     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 304     :disable-job: Whether to disable the job (default: false)
 305     :project-pattern: Project to trigger build against. (default: \*\*)
 306     :stream: Keyword representing a release code-name.
 307         Often the same as the branch. (default: master)
 308     :submodule-recursive: Whether to checkout submodules recursively.
 309         (default: true)
 310     :submodule-timeout: Timeout (in minutes) for checkout operation.
 311         (default: 10)
 312     :submodule-disable: Disable submodule checkout operation.
 313         (default: false)
 314     :tox-dir: Directory containing the project's Read The Docs tox.ini
 315     :doc-dir: Relative directory project's docs generated by tox
 316     :gerrit_verify_triggers: Override Gerrit Triggers.
 317     :gerrit_trigger_file_paths: Override file paths filter which checks which
 318         file modifications will trigger a build.
 319         **default**::
 320
 321             - compare-type: REG_EXP
 322               pattern: '^docs\/.*'