From ff490ac1ed8f71b44834dbb025a6f44f4611db39 Mon Sep 17 00:00:00 2001 From: Aric Gardner Date: Wed, 16 Oct 2019 11:03:39 -0400 Subject: [PATCH] Fix pattern to trigger on any files in docs/ Also do not trigger when docs in global-jjb submodule are updated. add TOX_ENVs to rtdv3 macro so that it only runs docs,docs-linkcheck add conditional-step so that project must have a .readthedocs.yaml for build to bother starting Signed-off-by: Aric Gardner Change-Id: I7716ceae30e0b460da0bd427b0670a6e1db1688c --- docs/jjb/lf-macros.rst | 9 ++- docs/jjb/{lf-rtdv2-jobs.rst => lf-rtdv3-jobs.rst} | 92 ++++++++++++++-------- jjb/lf-macros.yaml | 21 +++-- jjb/lf-rtdv2-job-groups.yaml | 7 -- jjb/lf-rtdv3-job-groups.yaml | 7 ++ jjb/{lf-rtdv2-jobs.yaml => lf-rtdv3-jobs.yaml} | 30 ++++--- .../notes/lf-rtdv3-jobs-e124c05d5cd0da1e.yaml | 6 ++ shell/{rtdv2.sh => rtdv3.sh} | 6 +- 8 files changed, 111 insertions(+), 67 deletions(-) rename docs/jjb/{lf-rtdv2-jobs.rst => lf-rtdv3-jobs.rst} (70%) delete mode 100644 jjb/lf-rtdv2-job-groups.yaml create mode 100644 jjb/lf-rtdv3-job-groups.yaml rename jjb/{lf-rtdv2-jobs.yaml => lf-rtdv3-jobs.yaml} (88%) create mode 100644 releasenotes/notes/lf-rtdv3-jobs-e124c05d5cd0da1e.yaml rename shell/{rtdv2.sh => rtdv3.sh} (95%) diff --git a/docs/jjb/lf-macros.rst b/docs/jjb/lf-macros.rst index 9b9b0896..f3eae1be 100644 --- a/docs/jjb/lf-macros.rst +++ b/docs/jjb/lf-macros.rst @@ -259,15 +259,16 @@ ReadTheDocs verify script. Installs and runs tox. :doc-dir: Document directory. :python-version: Python version. -lf-rtdv2-build +lf-rtdv3-build --------------- -ReadTheDocs Version 2 verify and merge scripts. -This is an update to the read the docs scripts that leverages the new Read the Docs v3 api +Read the docs scripts that leverage the new Read the Docs v3 api `RTD v3 API `_ -Runs tox to verify that the docs are good and then runs the RTDv2 shell script. +Runs tox to verify that the docs are good and then runs the RTDv3 shell script. This script handles creating projects as needed, assiging subprojects to the main read the docs project and triggering builds to update the documentation. +Jobs will run but skip verify bits until a .readthedocs.yaml is found in the root +of their repository. check-info-votes diff --git a/docs/jjb/lf-rtdv2-jobs.rst b/docs/jjb/lf-rtdv3-jobs.rst similarity index 70% rename from docs/jjb/lf-rtdv2-jobs.rst rename to docs/jjb/lf-rtdv3-jobs.rst index c2fd2cd7..b272bc1d 100644 --- a/docs/jjb/lf-rtdv2-jobs.rst +++ b/docs/jjb/lf-rtdv3-jobs.rst @@ -1,21 +1,64 @@ -.. _lf-global-jjb-rtdv2-jobs: +.. _lf-global-jjb-rtdv3-jobs: ########################## -ReadTheDocs Version:2 Jobs +ReadTheDocs Version:3 Jobs ########################## -This is a global job that only needs to be added once to your project's ci-mangement git repository. It leverages the read the docs v3 api to create projects on the fly, as well as set up subproject associations with the master doc. +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: + +.. 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: + +.. code-block:: bash + + tox -e docs,docs-linkcheck + + +Admin setup: + +This is a global job that only needs to be added once to your project's ci-mangement git +repository. It leverages the read the docs v3 api to create projects on the fly, as well +as setting up subproject associations with the master doc. + +Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the +root of the repository The master doc must be defined in jenkins-config/global-vars-{production|sandbox}.sh +Normally this project is called doc or docs or documentation and all other docs build will +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 -In this way sandbox jobs will create docs with a test suffix and will not stomp on production documentation. +In this way sandbox jobs will create docs with a test suffix and will not stomp on production +documentation. Example job config: @@ -25,10 +68,10 @@ example file: ci-management/jjb/rtd/rtd.yaml --- - project: - name: rtdv2-verify-global + name: rtdv3-global-verify build-node: centos7-builder-1c-1g jobs: - - rtdv2-verify-global + - rtdv3-global-verify stream: - master: branch: master @@ -36,10 +79,10 @@ example file: ci-management/jjb/rtd/rtd.yaml branch: stable/{stream} - project: - name: rtdv2-merge-global + name: rtdv3-global-merge build-node: centos7-builder-1c-1g jobs: - - rtdv2-merge-global + - rtdv3-global-merge stream: - master: branch: master @@ -53,10 +96,10 @@ Or add both jobs via a job group: --- - project: - name: rtdv2-global + name: rtdv3-global build-node: centos7-builder-1c-1g jobs: - - rtdv2-global + - rtdv3-global stream: - master: branch: master @@ -79,7 +122,7 @@ Merge job will trigger a build to update docs. Macros ====== -lf-rtdv2-common +lf-rtdv3-common --------------- RTD verify and merge jobs are the same except for their scm, trigger, and @@ -89,13 +132,13 @@ builders definition. This anchor is the common template. Job Templates ============= -ReadTheDocs v2 Merge +ReadTheDocs v3 Merge -------------------- Merge job which triggers a build of the docs to readthedocs. :Template Names: - - rtdv2-merge-global-{stream} + - rtdv3-global-merge-{stream} :Comment Trigger: remerge @@ -128,24 +171,17 @@ Merge job which triggers a build of the docs to readthedocs. **default**:: - compare-type: REG_EXP - pattern: '.*\.css' - - compare-type: REG_EXP - pattern: '.*\.html' - - compare-type: REG_EXP - pattern: '.*\.rst' - - compare-type: REG_EXP - pattern: '.*\/conf.py' + pattern: '^docs\/.*' - -ReadTheDocs v2 Verify +ReadTheDocs v3 Verify --------------------- Verify job which runs a tox build of the docs project. -Also outputs some info on the build +Also outputs some info on the build. :Template Names: - - rtdv2-verify-global-{stream} + - rtdv3-global-verify-{stream} :Comment Trigger: recheck|reverify @@ -179,10 +215,4 @@ Also outputs some info on the build **default**:: - compare-type: REG_EXP - pattern: '.*\.css' - - compare-type: REG_EXP - pattern: '.*\.html' - - compare-type: REG_EXP - pattern: '.*\.rst' - - compare-type: REG_EXP - pattern: '.*\/conf.py' + pattern: '^docs\/.*' diff --git a/jjb/lf-macros.yaml b/jjb/lf-macros.yaml index 452c36a3..529254c9 100644 --- a/jjb/lf-macros.yaml +++ b/jjb/lf-macros.yaml @@ -275,13 +275,22 @@ - shell: !include-raw-escape: ../shell/rtd-verify.sh - builder: - name: lf-rtdv2-build + name: lf-rtdv3-build + builders: - - lf-infra-pre-build - - lf-infra-tox-install: - python-version: "python3" - - shell: !include-raw: ../shell/tox-run.sh - - shell: !include-raw: ../shell/rtdv2.sh + - conditional-step: + condition-kind: file-exists + condition-filename: .readthedocs.yaml + on-evaluation-failure: dont-run + steps: + - inject: + properties-content: | + TOX_ENVS=docs,docs-linkcheck + - lf-infra-pre-build + - lf-infra-tox-install: + python-version: "python3" + - shell: !include-raw: ../shell/tox-run.sh + - shell: !include-raw: ../shell/rtdv3.sh - builder: name: check-info-votes diff --git a/jjb/lf-rtdv2-job-groups.yaml b/jjb/lf-rtdv2-job-groups.yaml deleted file mode 100644 index fdce6242..00000000 --- a/jjb/lf-rtdv2-job-groups.yaml +++ /dev/null @@ -1,7 +0,0 @@ ---- -- job-group: - name: "rtdv2-global" - - jobs: - - rtdv2-verify-global - - rtdv2-merge-global diff --git a/jjb/lf-rtdv3-job-groups.yaml b/jjb/lf-rtdv3-job-groups.yaml new file mode 100644 index 00000000..53083433 --- /dev/null +++ b/jjb/lf-rtdv3-job-groups.yaml @@ -0,0 +1,7 @@ +--- +- job-group: + name: "rtdv3-global" + + jobs: + - rtdv3-global-verify + - rtdv3-global-merge diff --git a/jjb/lf-rtdv2-jobs.yaml b/jjb/lf-rtdv3-jobs.yaml similarity index 88% rename from jjb/lf-rtdv2-jobs.yaml rename to jjb/lf-rtdv3-jobs.yaml index 8acfa5fe..a5054aae 100644 --- a/jjb/lf-rtdv2-jobs.yaml +++ b/jjb/lf-rtdv3-jobs.yaml @@ -1,6 +1,6 @@ --- -- lf_rtdv2_common: &lf_rtdv2_common - name: lf-rtdv2-common +- lf_rtdv3_common: &lf_rtdv3_common + name: lf-rtdv3-common ###################### # Default parameters # @@ -20,13 +20,7 @@ gerrit_trigger_file_paths: - compare-type: REG_EXP - pattern: '.*\.css' - - compare-type: REG_EXP - pattern: '.*\.html' - - compare-type: REG_EXP - pattern: '.*\.rst' - - compare-type: REG_EXP - pattern: '.*\/conf.py' + pattern: '^docs\/.*' ##################### # Job Configuration # @@ -59,12 +53,12 @@ files: - file-id: lftoolsini target: "$HOME/.config/lftools/lftools.ini" - - lf-rtdv2-build + - lf-rtdv3-build - job-template: - name: "rtdv2-verify-global-{stream}" - id: rtdv2-verify-global - <<: *lf_rtdv2_common + name: "rtdv3-global-verify-{stream}" + id: rtdv3-global-verify + <<: *lf_rtdv3_common # yamllint disable-line rule:key-duplicates stream: master @@ -100,6 +94,10 @@ - branch-compare-type: "ANT" branch-pattern: "**/{branch}" file-paths: "{obj:gerrit_trigger_file_paths}" + forbidden-file-paths: + - compare-type: REG_EXP + pattern: ".*global-jjb.*" + skip-vote: successful: "{gerrit-skip-vote}" failed: "{gerrit-skip-vote}" @@ -107,9 +105,9 @@ notbuilt: "{gerrit-skip-vote}" - job-template: - name: "rtdv2-merge-global-{stream}" - id: rtdv2-merge-global - <<: *lf_rtdv2_common + name: "rtdv3-global-merge-{stream}" + id: rtdv3-global-merge + <<: *lf_rtdv3_common ###################### # Default parameters # diff --git a/releasenotes/notes/lf-rtdv3-jobs-e124c05d5cd0da1e.yaml b/releasenotes/notes/lf-rtdv3-jobs-e124c05d5cd0da1e.yaml new file mode 100644 index 00000000..672d9021 --- /dev/null +++ b/releasenotes/notes/lf-rtdv3-jobs-e124c05d5cd0da1e.yaml @@ -0,0 +1,6 @@ +--- +features: > + Read-the-docs job will run but skip its verification bits unless the repo has + .readthedocs.yaml file in the root of its repository. This allows projects to + commit changes to their docs/ dir without having to configure the read the + docs builds. diff --git a/shell/rtdv2.sh b/shell/rtdv3.sh similarity index 95% rename from shell/rtdv2.sh rename to shell/rtdv3.sh index 714821b4..c1014f46 100644 --- a/shell/rtdv2.sh +++ b/shell/rtdv3.sh @@ -8,7 +8,7 @@ # which accompanies this distribution, and is available at # http://www.eclipse.org/legal/epl-v10.html ############################################################################## -echo "---> rtd-verify.sh" +echo "---> rtdv3.sh" set -euo pipefail project_dashed="${PROJECT////-}" @@ -33,12 +33,12 @@ if [[ "$JOB_NAME" =~ "verify" ]]; then echo "INFO: Project not found, merge will create project https://$rtdproject.readthedocs.io" fi -echo "INFO: Merge will run" -echo "INFO: lftools rtd project-build-trigger $rtdproject $STREAM" +echo "INFO: Verify job completed" fi if [[ "$JOB_NAME" =~ "merge" ]]; then +echo "INFO: Running merge job" # This retuns null if project exists. project_exists=false -- 2.16.6