From f09897651a64bbfa1d3424ca58d09cbb2af382cf Mon Sep 17 00:00:00 2001 From: Aric Gardner Date: Thu, 6 Feb 2020 13:22:07 -0500 Subject: [PATCH] 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 Change-Id: I6b18dc27e605dc28cb4420a5591a911e956df337 --- docs/jjb/lf-rtdv3-jobs.rst | 44 ++++++++++++++++++---- jjb/lf-rtdv3-jobs.yaml | 2 + .../notes/lf-rtdv3-jobs-fc8b839cb2a6db9f.yaml | 8 ++++ shell/tox-run.sh | 3 +- 4 files changed, 49 insertions(+), 8 deletions(-) create mode 100644 releasenotes/notes/lf-rtdv3-jobs-fc8b839cb2a6db9f.yaml diff --git a/docs/jjb/lf-rtdv3-jobs.rst b/docs/jjb/lf-rtdv3-jobs.rst index 85a1480e..15dc81e4 100644 --- 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 51ee59f9..d78a59b0 100644 --- 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 index 00000000..67309f3e --- /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 e87c98f2..c955466c 100644 --- 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" -- 2.16.6