opendev/base-jobs
Code Issues Proposed changes

Add nox-docs base jobs

Browse Source 
This adds a copy of the tox-docs related jobs but using nox instead.

Depends-On: https://review.opendev.org/868134
Change-Id: I445202f366c748191fe6a05e145c05cbad1bb8f5
This commit is contained in:
James E. Blair 2022-12-20 09:08:32 -08:00
parent 8a7b3895d4
commit 675ff8b712
8 changed files with 263 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/source/documentation-jobs.rst
View File

@ -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

3
playbooks/nox-docs/post.yaml Normal file
View File

@ -0,0 +1,3 @@
- hosts: all
roles:
- fetch-sphinx-tarball

5
playbooks/nox-docs/pre.yaml Normal file
View File

@ -0,0 +1,5 @@
- hosts: all
roles:
- bindep
- ensure-nox
- ensure-python

37
playbooks/nox-docs/publish.yaml Normal file
View File

@ -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

4
playbooks/nox-docs/run.yaml Normal file
View File

@ -0,0 +1,4 @@
- hosts: all
roles:
- revoke-sudo
- nox

105
zuul.d/jobs.yaml
View File

@ -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: |

105
zuul.d/nox-jobs.yaml Normal file
View File

@ -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

105
zuul.d/tox-jobs.yaml Normal file
View File

@ -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