Add opendev docs build/promote jobs

This is a new style of docs job which transfers data
via tarballs and can publish branch-tip documentation
in the promote pipeline.

Depends-On: https://review.openstack.org/645384
Change-Id: I6f30f9c7016f54ee66d90c6dc3e6d9c603724b10

playbooks/docs/promote.yaml

@@ -0,0 +1,40 @@
+- hosts: localhost
+  tasks:
+    - name: Download docs archive
+      include_role:
+        name: download-artifact
+      vars:
+        download_artifact_job: opendev-tox-docs
+        download_artifact_api: "https://zuul.opendev.org/api/tenant/{{ zuul.tenant }}"
+        download_artifact_name: docs_archive
+        download_artifact_pipeline: gate
+    - name: Create working directory
+      file:
+        path: "{{ zuul.executor.work_root }}/docs"
+        state: directory
+    - name: Extract docs archive
+      unarchive:
+        src: "{{ zuul.executor.work_root }}/docs-html.tar.bz2"
+        dest: "{{ zuul.executor.work_root }}/docs"
+    - name: Write branch marker text
+      copy:
+        dest: "{{ zuul.executor.work_root }}/docs/.root-marker"
+        content: "Project: {{ zuul.project.name }} Branch: {{ zuul.branch }} Build: {{ zuul.build }} Revision: {{ zuul.ref }}"
+    - name: Set publication directory to latest
+      when: "zuul.branch == 'master'"
+      set_fact:
+        publication_dir: latest
+    - name: Set publication directory to branch
+      when: "zuul.branch != 'master'"
+      set_fact:
+        publication_dir: "{{ zuul.branch }}"
+    - name: Create redirect htaccess file
+      copy:
+        dest: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/.htaccess"
+        content: "Redirect 302 /{{ zuul.project.name }} /{{ zuul.project.name }}/latest"
+    - name: Upload to AFS
+      include_role:
+        name: upload-afs
+      vars:
+        afs_source: "{{ zuul.executor.work_root }}/docs/"
+        afs_target: "/afs/.openstack.org/project/opendev.org/docs/{{ zuul.project.name }}/{{ publication_dir }}"

playbooks/tox-docs/post.yaml

@@ -0,0 +1,4 @@
+- hosts: all
+  roles:
+    - fetch-tox-output
+    - fetch-sphinx-tarball

playbooks/tox-docs/pre.yaml

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

playbooks/tox-docs/run.yaml

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

zuul.yaml

@@ -221,6 +221,30 @@
       .. include:: ../../playbooks/docker-image/README.rst
       .. include:: ../../playbooks/docker-image/credentials.rst
 
+- 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
+    success-url: docs/
+
+- job:
+    name: opendev-promote-docs
+    description: |
+      Publish a previously built documentation tarball.
+    run: playbooks/docs/promote.yaml
+    nodeset:
+      nodes: []
+
 - project:
     templates:
       - build-tox-docs