Adjust cmake-sonar template and script

[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..15dc81e 100644 (file)
--- a/docs/jjb/lf-rtdv3-jobs.rst
+++ b/docs/jjb/lf-rtdv3-jobs.rst
@@ -30,36 +30,86 @@ recent one under the title "stable."  For more details please see
 control this process using Jenkins job configuration parameters as
 discussed below.
 
 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, 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, 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
 
 
 .. 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:
+   .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.
+
+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 "." the tox.ini must be
+reconfigured with the correct relative paths.
+
+Additionally, you must also modify 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 these files are correctly configured in your repository you can test
+locally:

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

-    tox -e docs,docs-linkcheck
+   tox -e docs,docs-linkcheck
+
+
+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:
+
+From:
+
+.. code-block:: bash
+
+   default-version: latest
+
+To:
+
+.. code-block:: bash
+
+   default-version: ReleaseBranchName

 
 
 Admin setup:
 
 
 Admin setup:


@@ -78,10 +128,13 @@ Normally this project is called doc or docs or documentation and all other docs
 be set as a subproject of this job.
 
 examples:
 be set 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.
 
 In this way sandbox jobs will create docs with a test suffix and will not stomp on production
 documentation.


@@ -92,44 +145,72 @@ 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
-
+   # 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, and will be covered by a diffrent set of jobs once these are proven.
 
 
 Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
 


@@ -137,13 +218,14 @@ Job requires an lftools config section, this is to provide api access to read th
 
 .. code-block:: bash
 
 
 .. 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 assign a project as a subproject of the master project.
 Merge job will trigger a build to update docs.
 
 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
 ======
 
 Macros
 ======


@@ -179,9 +261,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 +273,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 +318,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.