X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=blobdiff_plain;f=docs%2Fjjb%2Flf-rtdv3-jobs.rst;h=2f4a79a7a879b50eb80ac38128e282757846893e;hb=35e5c8dbf87dc8657bfa1c2631d641f56d81ed07;hp=8fe73f9b880abafcaf85fe44cda4c0bd66004491;hpb=026509df164f628deb0f4660a172cca364ff58ae;p=releng%2Fglobal-jjb.git diff --git a/docs/jjb/lf-rtdv3-jobs.rst b/docs/jjb/lf-rtdv3-jobs.rst index 8fe73f9b..2f4a79a7 100644 --- a/docs/jjb/lf-rtdv3-jobs.rst +++ b/docs/jjb/lf-rtdv3-jobs.rst @@ -4,28 +4,28 @@ ReadTheDocs Version:3 Jobs ########################## -ReadTheDocs V3 jobs support documentation that is structured as a -master documentation project plus a sub-project for each software -component. The master project files are usually maintained in a -"docs" git repository and should contain an index with links to all -the sub-projects. Each sub-project must maintain its documentation -files in a "docs" subdirectory within that software component's git -repository. +ReadTheDocs supports the nesting of projects, by configuring a project as a +subproject of another project. This allows for documentation projects to share +a search index and a namespace or custom domain, while still maintained +independently of each other. + +The master Read The Docs project files, maintained in a "docs" Git repository +should contain an index with links to all the sub-projects. Each sub-project +must maintain its documentation files in a "docs" subdirectory within that +software component's Git repository. The RTDv3 Jenkins jobs publish documentation by triggering builds at ReadTheDocs.io. That build process clones the appropriate repository -and transforms Real Simple Text (RST) and other files into HTML. -Master project builds are performed separately from sub-project -builds. - -The ReadTheDocs site supports multiple versions of documentation for -the master project and every sub-project. Every project should have a -development branch that's published at ReadTheDocs under the title -"latest"; in git this is usually the "master" branch. Most projects -also declare releases periodically. ReadTheDocs automatically detects -the creation of git branches and git tags, and publishes the most -recent one under the title "stable." For more details please see -`ReadTheDocs Versions +and transforms reStructuredText (RST) and other files into HTML. +All project's Read the Docs builds separately from sub-project builds. + +The Read The Docs site supports versioned documentation for the master project +and every sub-project. Every project should have a development branch that's +published at ReadTheDocs under the title "latest"; in Git this is the "master" +branch although can be different in some projects. Most projects also declare +releases periodically. ReadTheDocs automatically detects the creation of git +branches and git tags, and publishes the most recent one under the title +"stable." For more details please see `ReadTheDocs Versions `_. Teams can control this process using Jenkins job configuration parameters as discussed below. @@ -33,9 +33,9 @@ discussed below. User setup ---------- -To transform your rst documentation into a read the docs page, this job must be -configured and created as described in Admin setup below. Once this is complete -the following files must be added to your repository: +To transform your rst documentation into a Read The Docs page, configure as +described in Admin setup below. Once this is complete, add the following files +to your repository: .. code-block:: bash @@ -50,14 +50,27 @@ the following files must be added to your repository: docs/requirements-docs.txt docs/conf.py -Rather than have you copy and paste these files from a set of docs here, the +Rather than copying and pasting these files from a set of docs here, the following repo contains a script that will do this for you. Please refer to the -explanation presented in: https://github.com/lfit-sandbox/test. This is all -currently a beta feature, so feedback is encouraged. The script -`docs_script.sh` is not needed, you can copy the files by hand if you prefer. +explanation presented in: . This is a +beta feature, so please send feedback on your experiences. Once complete, the +script ``docs_script.sh`` is not needed. You can copy the files by hand if you +prefer. + +The default location of the tox.ini file is in the git repository root +directory. Optionally your documentation lead may decide to store all tox files +within the required "docs" subdirectory by setting configuration option +"tox-dir" to value "docs/" as discussed below. + +If your project's tox dir is ``docs/`` and not ``.``, update the tox.ini +configuration with the correct relative paths. -Once these files are correctly configured in your repository you can test -locally: +You must also set the doc-dir. For example, from the default of +``doc-dir: "docs/_build/html"`` to ``doc-dir: "_build/html"``, as the relative +path in the tox run has changed. + +Once configured, in your repository you can build the rst files locally to +test: .. code-block:: bash @@ -68,23 +81,15 @@ Stable Branch Instructions -------------------------- If your project does not create branches, you can skip this step. -Once you branch your project modify your conf.yaml and add the following line: - -.. code-block:: bash - - version: 'ReleaseBranchName' - -This will update the docs and change "master" on the top bar to your branch -name. This change should be done against your release branch, this change will -trigger a Read The Docs build which will create a new landing point for your -documentation. -This landing point is called /stable/ and is selectable as a version in the -bottom right corner of all Read The Docs pages. Once all projects have -branched and modified their conf.py they will have available their /stable/ -documentation. The process to release the documentation (that is to change the -default landing point of your docs from /latest/ to /stable/) is to change the -default-version in the jenkins job config as follows: +For Read The Docs to see your new branch, trigger a build to force RTD to run +an update. Use a trivial change to any file in your project's ``/docs/`` +directory on your newly minted branch to trigger a build and activate your +project's new branch on Read The Docs. This will create a new selectable +version in the bottom right corner of your project's Read The Docs page. +Once all projects have branched the process to release the documentation +(that is to change the default landing point of your docs from /latest/ to /branchname/) +is to change the default-version in the jenkins job config as follows: From: @@ -100,19 +105,20 @@ To: Admin setup: +------------ -This is a global job that only needs to be added once to your project's ci-mangement git -repository. It leverages the read the docs v3 api to create projects on the fly, as well -as setting up subproject associations with the master doc. +This part of the documentation explains how to enable this job so that It will trigger +on docs/* changes for all projects in a Gerrit instance. It leverages the +Read The Docs v3 api to create projects on the fly, as well as setting up +sub-project associations with the master doc. -Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the -root of the repository +A ``.readthedocs.yaml`` must exist in the root of the repository otherwise the +jobs will run but skip actual verification. -The master doc must be defined in -jenkins-config/global-vars-{production|sandbox}.sh +Define the master doc in jenkins-config/global-vars-{production|sandbox}.sh -Normally this project is called doc or docs or documentation and all other docs build will -be set as a subproject of this job. +This project named "doc" or "docs" or "documentation" will set all other docs +builds as a subproject of this job. examples: @@ -137,6 +143,8 @@ example file: ci-management/jjb/rtd/rtd.yaml name: rtdv3-global-verify build-node: centos7-builder-1c-1g default-version: latest + tox-dir: "." + doc-dir: "docs/_build/html" jobs: - rtdv3-global-verify stream: @@ -148,6 +156,8 @@ example file: ci-management/jjb/rtd/rtd.yaml - project: name: rtdv3-global-merge default-version: latest + tox-dir: "." + doc-dir: "docs/_build/html" build-node: centos7-builder-1c-1g jobs: - rtdv3-global-merge @@ -158,23 +168,44 @@ example file: ci-management/jjb/rtd/rtd.yaml branch: stable/{stream} Or add both jobs via a job group: +This real-world example also shows how to configure your builds to use +a tox.ini that lived inside your docs/ dir .. code-block:: bash + # Global read the docs version 3 jobs + # + # jobs trigger for all projects, all branches + # on any changes to files in a docs/ directory + # and publish subprojects to readthedocs.io + # using credentials from Jenkins settings --- + - project: + name: rtdv3-view + project-name: rtdv3-global + views: + - project-view + - project: name: rtdv3-global default-version: latest - build-node: centos7-builder-1c-1g + tox-dir: "docs/" + doc-dir: "_build/html" + build-node: centos7-builder-2c-1g + # override the default to ignore ref-updated-event (tag) + gerrit_merge_triggers: + - change-merged-event + - comment-added-contains-event: + comment-contains-value: remerge$ jobs: - - rtdv3-global + - rtdv3-global-verify + - rtdv3-global-merge stream: - master: - branch: master - + branch: '*' -Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven. +GitHub jobs must be per-project. Once proven, a different set of jobs will be available. Job requires an lftools config section, this is to provide api access to read the docs. @@ -184,7 +215,7 @@ Job requires an lftools config section, this is to provide api access to read th endpoint = https://readthedocs.org/api/v3/ token = [hidden] -Merge Job will create a project on read the docs if none exist. +Merge Job will create a project on Read The Docs if none exist. Merge Job will assign a project as a subproject of the master project. Merge job will trigger a build to update docs. Merge job will change the default version if needed. @@ -205,7 +236,7 @@ Job Templates ReadTheDocs v3 Merge -------------------- -Merge job which triggers a build of the docs to readthedocs. +Merge job which triggers a build of the docs to Read The Docs. :Template Names: - rtdv3-global-merge-{stream} @@ -235,7 +266,8 @@ Merge job which triggers a build of the docs to readthedocs. (default: 10) :submodule-disable: Disable submodule checkout operation. (default: false) - + :tox-dir: Directory containing the project's Read The Docs tox.ini + :doc-dir: Relative directory project's docs generated by tox :gerrit_merge_triggers: Override Gerrit Triggers. :gerrit_trigger_file_paths: Override file paths filter which checks which file modifications will trigger a build. @@ -279,7 +311,8 @@ Also outputs some info on the build. (default: 10) :submodule-disable: Disable submodule checkout operation. (default: false) - + :tox-dir: Directory containing the project's Read The Docs tox.ini + :doc-dir: Relative directory project's docs generated by tox :gerrit_verify_triggers: Override Gerrit Triggers. :gerrit_trigger_file_paths: Override file paths filter which checks which file modifications will trigger a build.