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 8fe73f9..15dc81e 100644 (file)
--- a/docs/jjb/lf-rtdv3-jobs.rst
+++ b/docs/jjb/lf-rtdv3-jobs.rst
@@ -54,7 +54,20 @@ 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.
+``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:
@@ -137,6 +150,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 +163,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,21 +175,42 @@ 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.
 
@@ -235,7 +273,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 +318,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.