Add nox-docs base jobs

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

Depends-On: https://review.opendev.org/868134
Change-Id: I445202f366c748191fe6a05e145c05cbad1bb8f5

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

playbooks/nox-docs/post.yaml

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

playbooks/nox-docs/pre.yaml

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

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

playbooks/nox-docs/run.yaml

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

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

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
+

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
+