Return preview artifact in fetch-sphinx-output

This adds an extra variable to the role which can be used to
better control the URL which is returned as the artifact.

Change-Id: Ifd270cbc2d4bd42418b89a3b3061748ce537ae42

roles/fetch-sphinx-output/README.rst

@@ -16,6 +16,13 @@ to the log root of the executor.
 
    Directory relative to zuul_work_dir where build output will be put.
 
+.. zuul:rolevar:: sphinx_output_dir
+   :default: html
+
+   Directory relative to sphinx_build_dir where sphinx output will be
+   put.  Unlike sphinx_build_dir, this will appear in the destination
+   directory and returned artifact URLs.
+
 .. zuul:rolevar:: sphinx_output_suffix
    :default: ''
 
@@ -24,7 +31,7 @@ to the log root of the executor.
    from the original path.
 
 .. zuul:rolevar:: sphinx_output_src
-   :default: {{ zuul_work_dir }}/{{ sphinx_build_dir }}/html{{ sphinx_output_suffix }}
+   :default: {{ zuul_work_dir }}/{{ sphinx_build_dir }}/{{ sphinx_output_dir }}{{ sphinx_output_suffix }}
 
    The location on the worker from which to fetch the generated sphinx
    content.  By default, the HTML doc build dir of the current

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

@@ -3,4 +3,5 @@ zuul_executor_dest: "{{ zuul.executor.log_root }}"
 zuul_work_dir: "{{ zuul.project.src_dir }}"
 sphinx_build_dir: doc/build
 sphinx_output_suffix: ""
-sphinx_output_src: "{{ zuul_work_dir }}/{{ sphinx_build_dir }}/html{{ sphinx_output_suffix }}"
+sphinx_output_dir: "html"
+sphinx_output_src: "{{ zuul_work_dir }}/{{ sphinx_build_dir }}/{{ sphinx_output_dir }}{{ sphinx_output_suffix }}"

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

@@ -4,3 +4,13 @@
     mode: pull
     src: "{{ sphinx_output_src }}"
     verify_host: true
+
+- name: Return artifact to Zuul
+  zuul_return:
+    data:
+      zuul:
+        artifacts:
+          - name: "Docs preview site"
+            url: "{{ sphinx_output_dir }}/"
+            metadata:
+              type: docs_site