docs/jjb/lf-rtdv3-jobs.rst

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