Add a opendev-publish-unversioned-tox-docs job

It's mildly annoying that, in the wake of tagging a new release,
documentation lags behind because we only publish in the promote
pipeline from what was built by the last change to merge in the
gate. There is an existing job which can build and publish
documentation in the release pipeline, but does so into a
version-specific path leading to multiple versioned copies of the
documentation.

For fast-moving projects it's not much of a problem
since there will be a new change coming along soon to refresh the
default version of the documents and reflect the recent tag in page
footers and release notes. In simple projects with only a single
branch and infrequent changes, however, there can be long periods of
time where the published documentation makes no indication of the
existence of the latest release. Address this with a new job which
publishes to "latest" instead of the tag name.

Note that this requires a copy of the existing secret, in order to
update the "tag" variable attached to it. Also worth noting, this
job could be run in parallel with the existing
opendev-publish-tox-docs job in the release pipeline for the same
project in order to get the benefits of both.

Change-Id: Ibd4f31b9d06137f9cc52bc1a07e1c37766494e7b

doc/source/documentation-jobs.rst

@@ -4,5 +4,6 @@ Documentation Jobs
 .. zuul:autojob:: opendev-tox-docs
 .. zuul:autojob:: opendev-publish-tox-docs-base
 .. zuul:autojob:: opendev-publish-tox-docs
+.. zuul:autojob:: opendev-publish-unversioned-tox-docs
 .. zuul:autojob:: opendev-promote-docs-base
 .. zuul:autojob:: opendev-promote-docs

zuul.d/jobs.yaml

@@ -305,6 +305,24 @@
       - 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

zuul.d/secrets.yaml

@@ -1,3 +1,29 @@
+- secret:
+    name: opendev-unversioned-docs
+    data:
+      keytab: !encrypted/pkcs1-oaep
+        - VYDeNL9oysY3I3KgseVeMCUpjowF4og2xqeY8ekc6UNGl1ohnGGza/UepKAblkScLRC5d
+          KSLZxjoH+Tg6Qs388nR7GF+HT5ml1aq2J52vaYc6X6X+n0RG6zpJOaZIxsNQclO/Iwd4m
+          R1iIZ89WKF+fg894L2f8VCBOVA9I8BPE0Z8va4ywFqrm7TFYFFWkSYyGKMIHRge27nkA3
+          SH5AaLYTzkNBHO4f5Xy/ouLilUa/sCMtOYyUYDsoOwqwitImxfDt1Vx0TfqxNyLCLLiDm
+          eGGVv/eL5Ae2byS/dFni8OYImcJxWwwc2f+lMgr/2UicfRYH8GXfIoXmSpud8/Cc39w5z
+          Pc08zTyRdXBgZZyRw46lCpwZmGPYZIlNr7iuxdypnXdo07udTx3Zj2RkSMjWiU72rgx7l
+          De3LpvN59uxsqTgemqzKjXIEa4cl1gw929/5EyDgfgmbhBgUFgScZ9UTwTl2JiWji3kH4
+          oeiYoA1y9AxuBSuqSIe1BQbFnl6XHnVoOvPX9ObjIUNwWUVkfYCMvyqpdSYcGG81vts40
+          BLNr7dnEAAz+yGqLLDYzAiV6IOVDuFutSK35YWisEu0QZDIyP9TOzh17+49tIbWyPZFiw
+          Gj8RrLn2EwsAQSXSYIGv2F0gjHKPugg8bFKS2E9rEnRGFEIutel6hnI9mlCUfU=
+      service_name: service/opendev-zuul@OPENSTACK.ORG
+      targets:
+        master:
+          path: "/afs/.openstack.org/project/opendev.org/docs/{zuul[project][name]}/latest"
+          redirect:
+            path: "/afs/.openstack.org/project/opendev.org/docs/{zuul[project][name]}/.htaccess"
+            content: "RedirectMatch 302 ^/{zuul[project][name]}/?$ /{zuul[project][name]}/latest/"
+        branch:
+          path: "/afs/.openstack.org/project/opendev.org/docs/{zuul[project][name]}/latest"
+        tag:
+          path: "/afs/.openstack.org/project/opendev.org/docs/{zuul[project][name]}/latest"
+
 - secret:
     name: opendev-zuul-docs
     data: