Fix: Update lf-infra-sonar macro to use JDK version

[releng/global-jjb.git] / docs / jjb / lf-rtdv3-jobs.rst

diff --git a/docs/jjb/lf-rtdv3-jobs.rst b/docs/jjb/lf-rtdv3-jobs.rst
index 04e1953..2f4a79a 100644 (file)
--- a/docs/jjb/lf-rtdv3-jobs.rst
+++ b/docs/jjb/lf-rtdv3-jobs.rst
@@ -4,84 +4,130 @@
 ReadTheDocs Version:3 Jobs
 ##########################
 
 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
 
 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

 <https://docs.readthedocs.io/en/stable/versions.html>`_.  Teams can
 control this process using Jenkins job configuration parameters as
 discussed below.
 
 <https://docs.readthedocs.io/en/stable/versions.html>`_.  Teams can
 control this process using Jenkins job configuration parameters as
 discussed below.
 

-User setup:
+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:
+
+.. 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
+
+   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:

 
 

-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:
+From:

 
 .. code-block:: bash
 
 
 .. 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:
+   default-version: latest
+
+To:

 
 .. code-block:: bash
 
 
 .. code-block:: bash
 

-    tox -e docs,docs-linkcheck
+   default-version: ReleaseBranchName

 
 
 Admin setup:
 
 
 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:
 
 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.
 
 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
 documentation.


@@ -92,58 +138,87 @@ example file: ci-management/jjb/rtd/rtd.yaml
 
 .. code-block:: bash
 
 
 .. 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:
 
 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
 
 
 
 .. 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
 
 
 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 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
 ======
 
 Macros
 ======


@@ -161,7 +236,7 @@ Job Templates
 ReadTheDocs v3 Merge
 --------------------
 
 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}
 
 :Template Names:
     - rtdv3-global-merge-{stream}


@@ -179,9 +254,10 @@ Merge job which triggers a build of the docs to readthedocs.
     :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)
     :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)
     :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.
     :stream: Keyword representing a release code-name.
         Often the same as the branch. (default: master)
     :submodule-recursive: Whether to checkout submodules recursively.


@@ -190,7 +266,8 @@ Merge job which triggers a build of the docs to readthedocs.
         (default: 10)
     :submodule-disable: Disable submodule checkout operation.
         (default: false)
         (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.
     :gerrit_merge_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths filter which checks which
         file modifications will trigger a build.


@@ -234,7 +311,8 @@ Also outputs some info on the build.
         (default: 10)
     :submodule-disable: Disable submodule checkout operation.
         (default: false)
         (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.
     :gerrit_verify_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths filter which checks which
         file modifications will trigger a build.