Add configurable doc-dir

[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 85a1480..15dc81e 100644 (file)
--- a/docs/jjb/lf-rtdv3-jobs.rst
+++ b/docs/jjb/lf-rtdv3-jobs.rst
@@ -54,7 +54,7 @@ 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
@@ -64,6 +64,11 @@ within the required "docs" subdirectory by setting configuration option
 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:
 
@@ -146,6 +151,7 @@ example file: ci-management/jjb/rtd/rtd.yaml
        build-node: centos7-builder-1c-1g
        default-version: latest
        tox-dir: "."
+       doc-dir: "docs/_build/html"
        jobs:
          - rtdv3-global-verify
        stream:
@@ -157,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
@@ -167,22 +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
-       tox-dir: "."
-       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.
 
@@ -245,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.
@@ -290,6 +319,7 @@ Also outputs some info on the build.
     :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.