control this process using Jenkins job configuration parameters as
discussed below.
-User setup:
+User setup
+----------
-To transform your rst documentation into a read the docs page, this job must be configured and
-created as described in Admin setup below. Once this is complete the following files must be
-added to your repository:
+To transform your rst documentation into a read the docs page, this job must be
+configured and created as described in Admin setup below. Once this is complete
+the following files must be added to your repository:
.. code-block:: bash
- .readthedocs.yaml
- tox.ini
- docs
- docs/_static
- docs/_static/logo.png
- docs/conf.yaml
- docs/favicon.ico
- docs/index.rst
- docs/requirements-docs.txt
- docs/conf.py
-
-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
-
-Once these files are correctly configured in your repository you can test locally:
+ .readthedocs.yaml
+ tox.ini
+ docs
+ docs/_static
+ docs/_static/logo.png
+ docs/conf.yaml
+ docs/favicon.ico
+ docs/index.rst
+ docs/requirements-docs.txt
+ docs/conf.py
+
+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.
+
+Once these files are correctly configured in your repository you can test
+locally:
.. code-block:: bash
- tox -e docs,docs-linkcheck
+ tox -e docs,docs-linkcheck
+
+
+Stable Branch Instructions
+--------------------------
+
+If your project does not create branches, you can skip this step.
+Once you branch your project modify your conf.yaml and add the following line:
+
+.. code-block:: bash
+
+ version: 'ReleaseBranchName'
+
+This will update the docs and change "master" on the top bar to your branch
+name. This change should be done against your release branch, this change will
+trigger a Read The Docs build which will create a new landing point for your
+documentation.
+
+This landing point is called /stable/ and is selectable as a version in the
+bottom right corner of all Read The Docs pages. Once all projects have
+branched and modified their conf.py they will have available their /stable/
+documentation. The process to release the documentation (that is to change the
+default landing point of your docs from /latest/ to /stable/) is to change the
+default-version in the jenkins job config as follows:
+
+From:
+
+.. code-block:: bash
+
+ default-version: latest
+
+To:
+
+.. code-block:: bash
+
+ default-version: ReleaseBranchName
Admin setup:
be set as a subproject of this job.
examples:
-global-vars-sandbox.sh:
-MASTER_RTD_PROJECT=doc-test
-global-vars-production.sh:
-MASTER_RTD_PROJECT=doc
+
+.. code-block:: bash
+
+ global-vars-sandbox.sh:
+ MASTER_RTD_PROJECT=doc-test
+ global-vars-production.sh:
+ MASTER_RTD_PROJECT=doc
In this way sandbox jobs will create docs with a test suffix and will not stomp on production
documentation.
.. code-block:: bash
- ---
- - project:
- name: rtdv3-global-verify
- build-node: centos7-builder-1c-1g
- jobs:
- - rtdv3-global-verify
- stream:
- - master:
- branch: master
- - foo:
- branch: stable/{stream}
-
- - project:
- name: rtdv3-global-merge
- build-node: centos7-builder-1c-1g
- jobs:
- - rtdv3-global-merge
- stream:
- - master:
- branch: master
- - foo:
- branch: stable/{stream}
+ ---
+ - project:
+ name: rtdv3-global-verify
+ build-node: centos7-builder-1c-1g
+ default-version: latest
+ jobs:
+ - rtdv3-global-verify
+ stream:
+ - master:
+ branch: master
+ - foo:
+ branch: stable/{stream}
+
+ - project:
+ name: rtdv3-global-merge
+ default-version: latest
+ build-node: centos7-builder-1c-1g
+ jobs:
+ - rtdv3-global-merge
+ stream:
+ - master:
+ branch: master
+ - foo:
+ branch: stable/{stream}
Or add both jobs via a job group:
.. code-block:: bash
- ---
- - project:
- name: rtdv3-global
- build-node: centos7-builder-1c-1g
- jobs:
- - rtdv3-global
- stream:
- - master:
- branch: master
+ ---
+ - project:
+ name: rtdv3-global
+ default-version: latest
+ build-node: centos7-builder-1c-1g
+ jobs:
+ - rtdv3-global
+ stream:
+ - master:
+ branch: master
Github jobs must be per project, and will be covered by a diffrent set of jobs once these are proven.
.. code-block:: bash
- [rtd]
- endpoint = https://readthedocs.org/api/v3/
- token = [hidden]
+ [rtd]
+ endpoint = https://readthedocs.org/api/v3/
+ token = [hidden]
Merge Job will create a project on read the docs if none exist.
Merge Job will assign a project as a subproject of the master project.
Merge job will trigger a build to update docs.
+Merge job will change the default version if needed.
Macros
======
:branch: Git branch to fetch for the build. (default: master)
:build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
:build-timeout: Timeout in minutes before aborting build. (default: 15)
- :project-pattern: Project to trigger build against. (default: \*\*)
- :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+ :default-version: default page to redirect to for documentation (default /latest/)
:disable-job: Whether to disable the job (default: false)
+ :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+ :project-pattern: Project to trigger build against. (default: \*\*)
:stream: Keyword representing a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
branch: master
stream: master
+ default-version: latest
disabled: "{disable-job}"
build-days-to-keep: 7
build-timeout: 15
- lf-infra-publish
builders:
- - config-file-provider:
- files:
- - file-id: lftoolsini
- target: "$HOME/.config/lftools/lftools.ini"
- - lf-rtdv3-build
+ - conditional-step:
+ condition-kind: file-exists
+ condition-filename: .readthedocs.yaml
+ on-evaluation-failure: dont-run
+ steps:
+ - config-file-provider:
+ files:
+ - file-id: lftoolsini
+ target: "$HOME/.config/lftools/lftools.ini"
+ - lf-infra-pre-build
+ - lf-infra-tox-install:
+ python-version: "python3"
+ - inject:
+ properties-content: |
+ TOX_ENVS=docs,docs-linkcheck
+ - lf-infra-tox-run:
+ parallel: "true"
+ - lf-rtdv3-build:
+ default-version: "{default-version}"
- job-template:
name: "rtdv3-global-verify-{stream}"
branches:
- branch-compare-type: "ANT"
branch-pattern: "**/{branch}"
+ - branch-compare-type: "ANT"
+ branch-pattern: "refs/tags/**"
file-paths: "{obj:gerrit_trigger_file_paths}"
forbidden-file-paths:
- compare-type: REG_EXP
branches:
- branch-compare-type: "ANT"
branch-pattern: "**/{branch}"
+ - branch-compare-type: "ANT"
+ branch-pattern: "refs/tags/**"
file-paths: "{obj:gerrit_trigger_file_paths}"
+ forbidden-file-paths:
+ - compare-type: REG_EXP
+ pattern: ".*global-jjb.*"
set -euo pipefail
project_dashed="${PROJECT////-}"
-umbrella="$(echo "$GERRIT_URL" | awk -F"." '{print $2}')"
+umbrella=$(echo "$GERRIT_URL" | awk -F'.' '{print $2}')
if [[ "$SILO" == "sandbox" ]]; then
rtdproject="$umbrella-$project_dashed-test"
else
echo "INFO:"
echo "INFO: Project: $PROJECT"
-echo "INFO: Read the Docs Project: https://$rtdproject.readthedocs.io"
-echo "INFO: Read the Docs master Project: https://$masterproject.readthedocs.io"
+echo "INFO: Read the Docs Sub Project: https://$rtdproject.readthedocs.io"
+echo "INFO: Read the Docs Master Project: https://$masterproject.readthedocs.io"
if [[ "$JOB_NAME" =~ "verify" ]]; then
fi
if [[ "$JOB_NAME" =~ "merge" ]]; then
-echo "INFO: Running merge job"
+echo "INFO: Performing merge action"
# This retuns null if project exists.
project_exists=false
if [[ "$rtdproject" != "$masterproject" ]]; then
subproject_exists=false
while read -r subproject; do
- if [[ "$subproject" == "$rtdproject" ]]; then
- subproject_exists=true
- break
- fi
+ if [[ "$subproject" == "$rtdproject" ]]; then
+ subproject_exists=true
+ break
+ fi
done < <(lftools rtd subproject-list "$masterproject")
if $subproject_exists; then
- echo "INFO: subproject relationship already created"
+ echo "INFO: subproject $rtdproject relationship already created"
else
- echo "INFO: Need to create subproject relationship"
+ echo "INFO: Creating subproject relationship"
lftools rtd subproject-create "$masterproject" "$rtdproject"
echo "INFO sleeping for 10 seconds"
sleep 10
fi
fi
- # api v3 method does not update latest whith stream.
- lftools rtd project-build-trigger "$rtdproject" "$STREAM"
- lftools rtd project-build-trigger "$rtdproject" latest
+ # api v3 method does not update /latest/ when master is triggered.
+ # Also, when we build anything other than master we want to trigger /stable/ as well.
+ # allow projects to change their landing page from latest to branch_name
+
+ current_version="$(lftools rtd project-details "$rtdproject" | yq -r .default_version)"
+ if [[ -z ${DEFAULT_VERSION:-} ]]; then
+ echo "DEFAULT_VERSION (default-version) value cannot be empty"
+ exit 1
+ fi
+ default_version="${DEFAULT_VERSION}"
+
+ echo "INFO: current default version $current_version"
+ if [[ $current_version != "$default_version" ]]; then
+ echo "INFO: Setting rtd landing page to $default_version"
+ lftools rtd project-update "$rtdproject" default_version="$default_version"
+ fi
+
+ lftools rtd project-build-trigger "$rtdproject" "$GERRIT_BRANCH"
+ if [[ $GERRIT_BRANCH == "master" ]]; then
+ echo "INFO: triggering latest"
+ lftools rtd project-build-trigger "$rtdproject" latest
+ else
+ echo "INFO: triggering stable"
+ lftools rtd project-build-trigger "$rtdproject" stable
+ fi
fi
Code Review / releng / global-jjb.git / commitdiff