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
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
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
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
If your project's tox dir is "docs/" and not "." the tox.ini must be
reconfigured with the correct relative paths.
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:
Once these files are correctly configured in your repository you can test
locally:
build-node: centos7-builder-1c-1g
default-version: latest
tox-dir: "."
build-node: centos7-builder-1c-1g
default-version: latest
tox-dir: "."
+ doc-dir: "docs/_build/html"
jobs:
- rtdv3-global-verify
stream:
jobs:
- rtdv3-global-verify
stream:
- project:
name: rtdv3-global-merge
default-version: latest
- 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
build-node: centos7-builder-1c-1g
jobs:
- rtdv3-global-merge
branch: stable/{stream}
Or add both jobs via a job group:
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
+ # 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
- 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$
+ - rtdv3-global-verify
+ - rtdv3-global-merge
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.
(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.
:submodule-disable: Disable submodule checkout operation.
(default: false)
:tox-dir: Directory containing the project's read the docs tox.ini
: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.
submodule-disable: true
submodule-timeout: 10
tox-dir: "."
submodule-disable: true
submodule-timeout: 10
tox-dir: "."
+ doc-dir: "docs/_build/html"
gerrit-skip-vote: false
gerrit_trigger_file_paths:
gerrit-skip-vote: false
gerrit_trigger_file_paths:
properties-content: |
TOX_ENVS=docs,docs-linkcheck
TOX_DIR={tox-dir}
properties-content: |
TOX_ENVS=docs,docs-linkcheck
TOX_DIR={tox-dir}
- lf-infra-tox-run:
parallel: "true"
- lf-rtdv3-build:
- lf-infra-tox-run:
parallel: "true"
- lf-rtdv3-build:
--- /dev/null
+---
+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
echo "---> tox-run.sh"
ARCHIVE_TOX_DIR="$WORKSPACE/archives/tox"
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
mkdir -p "$ARCHIVE_TOX_DIR"
cd "$WORKSPACE/$TOX_DIR" || exit 1
DOC_DIR="${DOC_DIR:-docs/_build/html}"
if [[ -d "$DOC_DIR" ]]; then
echo "---> Archiving generated docs"
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"
fi
test "$tox_status" -eq 0 || exit "$tox_status"