diff --git a/doc/source/documentation-jobs.rst b/doc/source/documentation-jobs.rst index 2dcb66c..7eea042 100644 --- a/doc/source/documentation-jobs.rst +++ b/doc/source/documentation-jobs.rst @@ -1,6 +1,10 @@ Documentation Jobs ================== +.. zuul:autojob:: opendev-nox-docs +.. zuul:autojob:: opendev-publish-nox-docs-base +.. zuul:autojob:: opendev-publish-nox-docs +.. zuul:autojob:: opendev-publish-unversioned-nox-docs .. zuul:autojob:: opendev-tox-docs .. zuul:autojob:: opendev-publish-tox-docs-base .. zuul:autojob:: opendev-publish-tox-docs diff --git a/playbooks/nox-docs/post.yaml b/playbooks/nox-docs/post.yaml new file mode 100644 index 0000000..b6f4eca --- /dev/null +++ b/playbooks/nox-docs/post.yaml @@ -0,0 +1,3 @@ +- hosts: all + roles: + - fetch-sphinx-tarball diff --git a/playbooks/nox-docs/pre.yaml b/playbooks/nox-docs/pre.yaml new file mode 100644 index 0000000..14f332f --- /dev/null +++ b/playbooks/nox-docs/pre.yaml @@ -0,0 +1,5 @@ +- hosts: all + roles: + - bindep + - ensure-nox + - ensure-python diff --git a/playbooks/nox-docs/publish.yaml b/playbooks/nox-docs/publish.yaml new file mode 100644 index 0000000..8546606 --- /dev/null +++ b/playbooks/nox-docs/publish.yaml @@ -0,0 +1,37 @@ +- hosts: localhost + tasks: + - name: Check execution context + when: "zuul.tag is not defined" + fail: + msg: "This playbook must be run in a tag-based pipeline (e.g., 'release')." + - include_role: + name: write-root-marker + vars: + root_marker_dir: "{{ zuul.executor.log_root }}/docs" + - name: Select target configuration + set_fact: + target_dict: "{{ afs.targets.tag }}" + - name: Set target path + set_fact: + target_dir: "{{ target_dict.path.format(zuul=zuul) }}" + - name: Adjust target path + when: "target_dict.regex is defined" + set_fact: + target_dir: "{{ target_dir | regex_replace(target_dict.regex.pattern, target_dict.regex.sub) }}" + - name: Get an AFS token + include_role: + name: create-afs-token + - name: Create publication directory + file: + path: "{{ target_dir }}" + state: directory + mode: 0755 + - name: Upload to AFS + include_role: + name: upload-afs-roots + vars: + afs_source: "{{ zuul.executor.log_root }}/docs/" + afs_target: "{{ target_dir }}" + - name: Destroy AFS token + include_role: + name: destroy-afs-token diff --git a/playbooks/nox-docs/run.yaml b/playbooks/nox-docs/run.yaml new file mode 100644 index 0000000..7f4913b --- /dev/null +++ b/playbooks/nox-docs/run.yaml @@ -0,0 +1,4 @@ +- hosts: all + roles: + - revoke-sudo + - nox diff --git a/zuul.d/jobs.yaml b/zuul.d/jobs.yaml index 727b1f5..9766377 100644 --- a/zuul.d/jobs.yaml +++ b/zuul.d/jobs.yaml @@ -224,111 +224,6 @@ - secret: opendev-intermediate-registry name: intermediate_registry -- job: - name: opendev-tox-docs - # This is not parented to tox-docs because the post playbook - # differs. - description: | - Build documentation with "tox". - - Uses tox with the ``docs`` environment. - vars: - tox_envlist: docs - bindep_profile: compile doc - pre-run: playbooks/tox-docs/pre.yaml - run: playbooks/tox-docs/run.yaml - post-run: playbooks/tox-docs/post.yaml - -- job: - name: opendev-publish-tox-docs-base - # This is not parented to opendev-tox-docs because the post - # playbook differs. - description: | - Publish a ref-based documentation build. - - Use this in the tag or release pipelines to publish a build - based on a newly-created tag. - - This is an abstract job intended to be inherited from in an - OpenDev tenant and an appropriate secret added. - - .. zuul:jobvar:: afs - :type: dict - - This is expected to be a Zuul Secret with these keys: - - .. zuul:jobvar:: keytab - - The AFS keytab for the service principal. - - .. zuul:jobvar:: service_name - - The name of the service princpal. - - .. zuul:jobvar:: targets - - This is a dict containing information about where docs should be - published. - - .. zuul:jobvar:: master - - This is expected to be a dict with a single key value pair: - `path: the full docs publication path to use if the job is - run on the master branch.` - - .. zuul:jobvar:: branch - - This is expected to be a dict with a key value pair: - `path: the full docs publication path to use if the job is run on - any other branch.` - - .. zuul:jobvar:: tag - - This is expected to be a dict with a key value pair: - `path: the full docs publication path to use if the job is run on - a tag.` - abstract: True - vars: - tox_envlist: docs - bindep_profile: compile doc - pre-run: playbooks/tox-docs/pre.yaml - run: playbooks/tox-docs/run.yaml - post-run: - - playbooks/tox-docs/post.yaml - - playbooks/tox-docs/publish.yaml - -- job: - name: opendev-publish-unversioned-tox-docs - parent: opendev-publish-tox-docs-base - description: | - Publish a ref-based documentation build to "latest" always. - - Use this in the tag or release pipelines to publish a build - based on a newly-created tag but published as if it were a - branch tip build instead. This is useful when the project has - only a single branch and multiple version-specific copies of - its documentation are undesirable, or when triggered by a tag - alongside a version-specific publication job. - post-run: playbooks/tox-docs/publish.yaml - secrets: - - secret: opendev-unversioned-docs - name: afs - pass-to-parent: true - -- job: - name: opendev-publish-tox-docs - parent: opendev-publish-tox-docs-base - description: | - Publish a ref-based documentation build. - - Use this in the tag or release pipelines to publish a build - based on a newly-created tag. - post-run: playbooks/tox-docs/publish.yaml - secrets: - - secret: opendev-zuul-docs - name: afs - pass-to-parent: true - - job: name: opendev-promote-docs-base description: | diff --git a/zuul.d/nox-jobs.yaml b/zuul.d/nox-jobs.yaml new file mode 100644 index 0000000..9999036 --- /dev/null +++ b/zuul.d/nox-jobs.yaml @@ -0,0 +1,105 @@ +- job: + name: opendev-nox-docs + # This is not parented to nox-docs because the post playbook + # differs. + description: | + Build documentation with "nox". + + Uses nox with the ``docs`` session. + vars: + nox_session: docs + bindep_profile: compile doc + pre-run: playbooks/nox-docs/pre.yaml + run: playbooks/nox-docs/run.yaml + post-run: playbooks/nox-docs/post.yaml + +- job: + name: opendev-publish-nox-docs-base + # This is not parented to opendev-nox-docs because the post + # playbook differs. + description: | + Publish a ref-based documentation build. + + Use this in the tag or release pipelines to publish a build + based on a newly-created tag. + + This is an abstract job intended to be inherited from in an + OpenDev tenant and an appropriate secret added. + + .. zuul:jobvar:: afs + :type: dict + + This is expected to be a Zuul Secret with these keys: + + .. zuul:jobvar:: keytab + + The AFS keytab for the service principal. + + .. zuul:jobvar:: service_name + + The name of the service princpal. + + .. zuul:jobvar:: targets + + This is a dict containing information about where docs should be + published. + + .. zuul:jobvar:: master + + This is expected to be a dict with a single key value pair: + `path: the full docs publication path to use if the job is + run on the master branch.` + + .. zuul:jobvar:: branch + + This is expected to be a dict with a key value pair: + `path: the full docs publication path to use if the job is run on + any other branch.` + + .. zuul:jobvar:: tag + + This is expected to be a dict with a key value pair: + `path: the full docs publication path to use if the job is run on + a tag.` + abstract: True + vars: + nox_session: docs + bindep_profile: compile doc + pre-run: playbooks/nox-docs/pre.yaml + run: playbooks/nox-docs/run.yaml + post-run: + - playbooks/nox-docs/post.yaml + - playbooks/nox-docs/publish.yaml + +- job: + name: opendev-publish-unversioned-nox-docs + parent: opendev-publish-nox-docs-base + description: | + Publish a ref-based documentation build to "latest" always. + + Use this in the tag or release pipelines to publish a build + based on a newly-created tag but published as if it were a + branch tip build instead. This is useful when the project has + only a single branch and multiple version-specific copies of + its documentation are undesirable, or when triggered by a tag + alongside a version-specific publication job. + post-run: playbooks/nox-docs/publish.yaml + secrets: + - secret: opendev-unversioned-docs + name: afs + pass-to-parent: true + +- job: + name: opendev-publish-nox-docs + parent: opendev-publish-nox-docs-base + description: | + Publish a ref-based documentation build. + + Use this in the tag or release pipelines to publish a build + based on a newly-created tag. + post-run: playbooks/nox-docs/publish.yaml + secrets: + - secret: opendev-zuul-docs + name: afs + pass-to-parent: true + diff --git a/zuul.d/tox-jobs.yaml b/zuul.d/tox-jobs.yaml new file mode 100644 index 0000000..973cc99 --- /dev/null +++ b/zuul.d/tox-jobs.yaml @@ -0,0 +1,105 @@ +- job: + name: opendev-tox-docs + # This is not parented to tox-docs because the post playbook + # differs. + description: | + Build documentation with "tox". + + Uses tox with the ``docs`` environment. + vars: + tox_envlist: docs + bindep_profile: compile doc + pre-run: playbooks/tox-docs/pre.yaml + run: playbooks/tox-docs/run.yaml + post-run: playbooks/tox-docs/post.yaml + +- job: + name: opendev-publish-tox-docs-base + # This is not parented to opendev-tox-docs because the post + # playbook differs. + description: | + Publish a ref-based documentation build. + + Use this in the tag or release pipelines to publish a build + based on a newly-created tag. + + This is an abstract job intended to be inherited from in an + OpenDev tenant and an appropriate secret added. + + .. zuul:jobvar:: afs + :type: dict + + This is expected to be a Zuul Secret with these keys: + + .. zuul:jobvar:: keytab + + The AFS keytab for the service principal. + + .. zuul:jobvar:: service_name + + The name of the service princpal. + + .. zuul:jobvar:: targets + + This is a dict containing information about where docs should be + published. + + .. zuul:jobvar:: master + + This is expected to be a dict with a single key value pair: + `path: the full docs publication path to use if the job is + run on the master branch.` + + .. zuul:jobvar:: branch + + This is expected to be a dict with a key value pair: + `path: the full docs publication path to use if the job is run on + any other branch.` + + .. zuul:jobvar:: tag + + This is expected to be a dict with a key value pair: + `path: the full docs publication path to use if the job is run on + a tag.` + abstract: True + vars: + tox_envlist: docs + bindep_profile: compile doc + pre-run: playbooks/tox-docs/pre.yaml + run: playbooks/tox-docs/run.yaml + post-run: + - playbooks/tox-docs/post.yaml + - playbooks/tox-docs/publish.yaml + +- job: + name: opendev-publish-unversioned-tox-docs + parent: opendev-publish-tox-docs-base + description: | + Publish a ref-based documentation build to "latest" always. + + Use this in the tag or release pipelines to publish a build + based on a newly-created tag but published as if it were a + branch tip build instead. This is useful when the project has + only a single branch and multiple version-specific copies of + its documentation are undesirable, or when triggered by a tag + alongside a version-specific publication job. + post-run: playbooks/tox-docs/publish.yaml + secrets: + - secret: opendev-unversioned-docs + name: afs + pass-to-parent: true + +- job: + name: opendev-publish-tox-docs + parent: opendev-publish-tox-docs-base + description: | + Publish a ref-based documentation build. + + Use this in the tag or release pipelines to publish a build + based on a newly-created tag. + post-run: playbooks/tox-docs/publish.yaml + secrets: + - secret: opendev-zuul-docs + name: afs + pass-to-parent: true +