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 To transform your rst documentation into a read the docs page, this job must be configured and
  36 created as described in Admin setup below. Once this is complete the following files must be
  37 added to your repository:
  38
  39 .. code-block:: bash
  40
  41     .readthedocs.yaml
  42     tox.ini
  43     docs
  44     docs/_static
  45     docs/_static/logo.png
  46     docs/conf.yaml
  47     docs/favicon.ico
  48     docs/index.rst
  49     docs/requirements-docs.txt
  50     docs/conf.py
  51
  52 Rather than have you copy and paste these files from a set of docs here, the following repo
  53 contains a script that will do this for you. Please refer to the explanation presented in:
  54 https://github.com/lfit-sandbox/test
  55 This is all currently a beta feature, so feedback is encouraged.
  56 the script `docs_script.sh` is not needed, you can copy the files by hand if you prefer
  57
  58 Once these files are correctly configured in your repository you can test locally:
  59
  60 .. code-block:: bash
  61
  62     tox -e docs,docs-linkcheck
  63
  64
  65 Admin setup:
  66
  67 This is a global job that only needs to be added once to your project's ci-mangement git
  68 repository. It leverages the read the docs v3 api to create projects on the fly, as well
  69 as setting up subproject associations with the master doc.
  70
  71 Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the
  72 root of the repository
  73
  74 The master doc must be defined in
  75 jenkins-config/global-vars-{production|sandbox}.sh
  76
  77 Normally this project is called doc or docs or documentation and all other docs build will
  78 be set as a subproject of this job.
  79
  80 examples:
  81 global-vars-sandbox.sh:
  82 MASTER_RTD_PROJECT=doc-test
  83 global-vars-production.sh:
  84 MASTER_RTD_PROJECT=doc
  85
  86 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
  87 documentation.
  88
  89 Example job config:
  90
  91 example file: ci-management/jjb/rtd/rtd.yaml
  92
  93 .. code-block:: bash
  94
  95     ---
  96     - project:
  97         name: rtdv3-global-verify
  98         build-node: centos7-builder-1c-1g
  99         jobs:
 100           - rtdv3-global-verify
 101         stream:
 102           - master:
 103               branch: master
 104           - foo:
 105               branch: stable/{stream}
 106
 107     - project:
 108         name: rtdv3-global-merge
 109         build-node: centos7-builder-1c-1g
 110         jobs:
 111           - rtdv3-global-merge
 112         stream:
 113           - master:
 114               branch: master
 115           - foo:
 116               branch: stable/{stream}
 117
 118 Or add both jobs via a job group:
 119
 120
 121 .. code-block:: bash
 122
 123     ---
 124     - project:
 125         name: rtdv3-global
 126         build-node: centos7-builder-1c-1g
 127         jobs:
 128           - rtdv3-global
 129         stream:
 130           - master:
 131               branch: master
 132
 133
 134 Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
 135
 136 Job requires an lftools config section, this is to provide api access to read the docs.
 137
 138 .. code-block:: bash
 139
 140     [rtd]
 141     endpoint = https://readthedocs.org/api/v3/
 142     token = [hidden]
 143
 144 Merge Job will create a project on read the docs if none exist.
 145 Merge Job will assign a project as a subproject of the master project.
 146 Merge job will trigger a build to update docs.
 147
 148 Macros
 149 ======
 150
 151 lf-rtdv3-common
 152 ---------------
 153
 154 RTD verify and merge jobs are the same except for their scm, trigger, and
 155 builders definition. This anchor is the common template.
 156
 157
 158 Job Templates
 159 =============
 160
 161 ReadTheDocs v3 Merge
 162 --------------------
 163
 164 Merge job which triggers a build of the docs to readthedocs.
 165
 166 :Template Names:
 167     - rtdv3-global-merge-{stream}
 168
 169 :Comment Trigger: remerge
 170
 171 :Required parameters:
 172
 173     :build-node: The node to run build on.
 174     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 175         in defaults.yaml)
 176
 177 :Optional parameters:
 178
 179     :branch: Git branch to fetch for the build. (default: master)
 180     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 181     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 182     :project-pattern: Project to trigger build against. (default: \*\*)
 183     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 184     :disable-job: Whether to disable the job (default: false)
 185     :stream: Keyword representing a release code-name.
 186         Often the same as the branch. (default: master)
 187     :submodule-recursive: Whether to checkout submodules recursively.
 188         (default: true)
 189     :submodule-timeout: Timeout (in minutes) for checkout operation.
 190         (default: 10)
 191     :submodule-disable: Disable submodule checkout operation.
 192         (default: false)
 193
 194     :gerrit_merge_triggers: Override Gerrit Triggers.
 195     :gerrit_trigger_file_paths: Override file paths filter which checks which
 196         file modifications will trigger a build.
 197         **default**::
 198
 199             - compare-type: REG_EXP
 200               pattern: '^docs\/.*'
 201
 202
 203 ReadTheDocs v3 Verify
 204 ---------------------
 205
 206 Verify job which runs a tox build of the docs project.
 207 Also outputs some info on the build.
 208
 209 :Template Names:
 210     - rtdv3-global-verify-{stream}
 211
 212 :Comment Trigger: recheck|reverify
 213
 214 :Required Parameters:
 215
 216     :build-node: The node to run build on.
 217     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 218         in defaults.yaml)
 219
 220 :Optional Parameters:
 221
 222     :branch: Git branch to fetch for the build. (default: master)
 223     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 224     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 225     :gerrit-skip-vote: Skip voting for this job. (default: false)
 226     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 227     :disable-job: Whether to disable the job (default: false)
 228     :project-pattern: Project to trigger build against. (default: \*\*)
 229     :stream: Keyword representing a release code-name.
 230         Often the same as the branch. (default: master)
 231     :submodule-recursive: Whether to checkout submodules recursively.
 232         (default: true)
 233     :submodule-timeout: Timeout (in minutes) for checkout operation.
 234         (default: 10)
 235     :submodule-disable: Disable submodule checkout operation.
 236         (default: false)
 237
 238     :gerrit_verify_triggers: Override Gerrit Triggers.
 239     :gerrit_trigger_file_paths: Override file paths filter which checks which
 240         file modifications will trigger a build.
 241         **default**::
 242
 243             - compare-type: REG_EXP
 244               pattern: '^docs\/.*'