Add configurable doc-dir

defaults to "docs/_build/html" needed for relative path
modifications if you change the tox-dir

tox-run also needs to handle these relative paths.

Signed-off-by: Aric Gardner <agardner@linuxfoundation.org>
Change-Id: I6b18dc27e605dc28cb4420a5591a911e956df337

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.

diff --git a/jjb/lf-rtdv3-jobs.yaml b/jjb/lf-rtdv3-jobs.yaml
index 51ee59f..d78a59b 100644 (file)
--- a/jjb/lf-rtdv3-jobs.yaml
+++ b/jjb/lf-rtdv3-jobs.yaml
@@ -18,6 +18,7 @@
     submodule-disable: true
     submodule-timeout: 10
     tox-dir: "."
+    doc-dir: "docs/_build/html"
     gerrit-skip-vote: false
 
     gerrit_trigger_file_paths:
@@ -67,6 +68,7 @@
                 properties-content: |
                   TOX_ENVS=docs,docs-linkcheck
                   TOX_DIR={tox-dir}
+                  DOC_DIR={doc-dir}
             - lf-infra-tox-run:
                 parallel: "true"
             - lf-rtdv3-build:

diff --git a/releasenotes/notes/lf-rtdv3-jobs-fc8b839cb2a6db9f.yaml b/releasenotes/notes/lf-rtdv3-jobs-fc8b839cb2a6db9f.yaml
new file mode 100644 (file)
index 0000000..67309f3
--- /dev/null
+++ b/releasenotes/notes/lf-rtdv3-jobs-fc8b839cb2a6db9f.yaml
@@ -0,0 +1,8 @@
+---
+fixes:
+  - |
+    Add configurable doc-dir defaults to "docs/_build/html"
+    needed for relative path modifications if you change the tox-dir
+    Modified tox-run.sh with "ARCHIVE_DOC_DIR" variable
+    so that relative paths can be handed when uploading generated
+    docs to the log server

diff --git a/shell/tox-run.sh b/shell/tox-run.sh
index e87c98f..c955466 100644 (file)
--- a/shell/tox-run.sh
+++ b/shell/tox-run.sh
@@ -11,6 +11,7 @@
 echo "---> tox-run.sh"
 
 ARCHIVE_TOX_DIR="$WORKSPACE/archives/tox"
+ARCHIVE_DOC_DIR="$WORKSPACE/archives/docs"
 mkdir -p "$ARCHIVE_TOX_DIR"
 cd "$WORKSPACE/$TOX_DIR" || exit 1
 
@@ -56,7 +57,7 @@ echo "Completed tox runs."
 DOC_DIR="${DOC_DIR:-docs/_build/html}"
 if [[ -d "$DOC_DIR" ]]; then
     echo "---> Archiving generated docs"
-    mv "$DOC_DIR" archives/
+    mv "$DOC_DIR" "$ARCHIVE_DOC_DIR"
 fi
 
 test "$tox_status" -eq 0 || exit "$tox_status"