ReadTheDocs Version:3 Jobs
##########################
-User setup:
+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 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
+<https://docs.readthedocs.io/en/stable/versions.html>`_. Teams can
+control this process using Jenkins job configuration parameters as
+discussed below.
+
+User setup
+----------
+
+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:
-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:
+.. code-block:: bash
+
+ .readthedocs.yaml
+ tox.ini
+ docs
+ docs/_static
+ docs/_static/logo.png
+ docs/conf.yaml
+ docs/favicon.ico
+ docs/index.rst
+ docs/requirements-docs.txt
+ docs/conf.py
+
+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 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.
+
+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
- .readthedocs.yaml
- tox.ini
- docs
- docs/_static
- docs/_static/logo.png
- docs/conf.yaml
- docs/favicon.ico
- docs/index.rst
- docs/requirements-docs.txt
- docs/conf.py
-
-Rather than have you copy and paste 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
-
-Once these files are correctly configured in your repository you can test locally:
+ tox -e docs,docs-linkcheck
+
+
+Stable Branch Instructions
+--------------------------
+
+If your project does not create branches, you can skip this step.
+
+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:
+
+.. code-block:: bash
+
+ default-version: latest
+
+To:
.. code-block:: bash
- tox -e docs,docs-linkcheck
+ default-version: ReleaseBranchName
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:
-global-vars-sandbox.sh:
-MASTER_RTD_PROJECT=doc-test
-global-vars-production.sh:
-MASTER_RTD_PROJECT=doc
+
+.. code-block:: bash
+
+ global-vars-sandbox.sh:
+ MASTER_RTD_PROJECT=doc-test
+ global-vars-production.sh:
+ MASTER_RTD_PROJECT=doc
In this way sandbox jobs will create docs with a test suffix and will not stomp on production
documentation.
.. code-block:: bash
- ---
- - project:
- name: rtdv3-global-verify
- build-node: centos7-builder-1c-1g
- jobs:
- - rtdv3-global-verify
- stream:
- - master:
- branch: master
- - foo:
- branch: stable/{stream}
-
- - project:
- name: rtdv3-global-merge
- build-node: centos7-builder-1c-1g
- jobs:
- - rtdv3-global-merge
- stream:
- - master:
- branch: master
- - foo:
- branch: stable/{stream}
+ ---
+ - project:
+ 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:
+ - master:
+ branch: master
+ - foo:
+ branch: stable/{stream}
+
+ - 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
+ stream:
+ - master:
+ branch: master
+ - foo:
+ 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
- ---
- - project:
- name: rtdv3-global
- build-node: centos7-builder-1c-1g
- jobs:
- - rtdv3-global
- stream:
- - master:
- branch: master
-
-
-Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
+ # 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
+ 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-verify
+ - rtdv3-global-merge
+ stream:
+ - master:
+ branch: '*'
+
+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.
.. code-block:: bash
- [rtd]
- endpoint = https://readthedocs.org/api/v3/
- token = [hidden]
+ [rtd]
+ 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.
Macros
======
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}
:branch: Git branch to fetch for the build. (default: master)
:build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
:build-timeout: Timeout in minutes before aborting build. (default: 15)
- :project-pattern: Project to trigger build against. (default: \*\*)
- :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+ :default-version: default page to redirect to for documentation (default /latest/)
:disable-job: Whether to disable the job (default: false)
+ :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+ :project-pattern: Project to trigger build against. (default: \*\*)
:stream: Keyword representing a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(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.
(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.
Code Review / releng / global-jjb.git / blobdiff