Add fetch-sphinx-tarball role

This is a new artifact-aware method of fetching sphinx tarballs,
meant to be used in docs promote jobs.

Change-Id: I9a01af9e36b959c4fa42f3c41b548c87bf2e1759

roles/fetch-sphinx-tarball/README.rst

@@ -0,0 +1,18 @@
+Collect output from a sphinx build as a tarball
+
+By default, this copies the output from the sphinx build on the worker
+to the log root of the executor as a tarball, and then extracts the
+archive into the log root for viewing.
+
+**Role Variables**
+
+.. zuul:rolevar:: sphinx_build_dir
+   :default: doc/build
+
+   Directory relative to zuul_work_dir where build output should be
+   found.
+
+.. zuul:rolevar:: zuul_work_dir
+   :default: {{ zuul.project.src_dir }}
+
+   The location of the main working directory of the job.

roles/fetch-sphinx-tarball/defaults/main.yaml

@@ -0,0 +1,3 @@
+---
+zuul_work_dir: "{{ zuul.project.src_dir }}"
+sphinx_build_dir: doc/build

roles/fetch-sphinx-tarball/tasks/html.yaml

@@ -0,0 +1,43 @@
+- name: Create temporary HTML archive file
+  tempfile:
+    state: file
+    suffix: ".tar.bz2"
+  register: html_archive
+
+- name: Archive HTML
+  command: "tar -f {{ html_archive.path }} -C {{ zuul_work_dir }}/{{ sphinx_build_dir }}/html -cj ."
+  args:
+    warn: false
+
+- name: Fetch archive HTML
+  synchronize:
+    dest: "{{ zuul.executor.log_root }}/docs-html.tar.bz2"
+    mode: pull
+    src: "{{ html_archive.path }}"
+    verify_host: true
+
+- name: Create browseable HTML directory
+  delegate_to: localhost
+  file:
+    path: "{{ zuul.executor.log_root }}/docs"
+    state: directory
+
+- name: Extract archive HTML
+  delegate_to: localhost
+  unarchive:
+    src: "{{ zuul.executor.log_root }}/docs-html.tar.bz2"
+    dest: "{{ zuul.executor.log_root }}/docs"
+
+- name: Return artifact to Zuul
+  zuul_return:
+    data:
+      zuul:
+        artifacts:
+          - name: "docs_archive"
+            url: "docs-html.tar.bz2"
+            metadata:
+              type: docs_archive
+          - name: "docs_site"
+            url: "docs/"
+            metadata:
+              type: docs_site

roles/fetch-sphinx-tarball/tasks/main.yaml

@@ -0,0 +1,15 @@
+- name: Inspect sphinx build directory
+  find:
+    file_type: any
+    paths: "{{ zuul_work_dir }}/{{ sphinx_build_dir }}"
+  register: sphinx_dir
+
+- name: Parse sphinx build directory
+  set_fact:
+    sphinx_dir: "{{sphinx_dir.files | map(attribute='path') | map('regex_replace', '^.*/(.*)$', '\\1') | list}}"
+
+- name: Process sphinx HTML
+  when: "'html' in sphinx_dir"
+  include_tasks: html.yaml
+
+# Other sphinx output processing can be added here.