Handle sphinx PDF files

This enhances fetch-sphinx-tarball to fetch PDF files as well if
they are published

For now, it collects a single PDF file since sphinx only generates one.
The name of the PDF file is not known in advance.

The publishing is done with https://review.opendev.org/678142.
This will then be used by https://review.opendev.org/664555.

Change-Id: I872ab1f696495dc40cb845e0eee5f6f0ffe892d8

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

@@ -12,4 +12,8 @@
   when: "'html' in sphinx_dir"
   include_tasks: html.yaml
 
+- name: Process sphinx PDF
+  when: "'pdf' in sphinx_dir"
+  include_tasks: pdf.yaml
+
 # Other sphinx output processing can be added here.

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

@@ -0,0 +1,44 @@
+# Sphinx builds a single PDF, the name of the PDF is not known.
+# Let's be safe and accept multiple PDFs but only return the first
+# one.
+
+- name: Search PDF files under sphinx build directory
+  find:
+    paths: "{{ zuul_work_dir }}/{{ sphinx_build_dir }}/pdf/"
+    file_type: file
+    patterns: "*.pdf"
+  register: pdf_files
+
+- name: Report no PDF to be uploaded
+  debug:
+    msg: "Found no PDF to upload"
+  when: pdf_files.matched == 0
+
+- name: Check for single PDF
+  debug:
+    msg: "Multiple PDF found, only grabbing first one"
+  when: pdf_files.matched > 1
+
+- name: Create PDF directory
+  delegate_to: localhost
+  file:
+    path: "{{ zuul.executor.log_root }}/pdf"
+    state: directory
+
+- name: Fetch PDF files
+  synchronize:
+    dest: "{{ zuul.executor.log_root }}/pdf/{{ pdf_files.files[0].path | basename }}"
+    mode: pull
+    src: "{{ pdf_files.files[0].path }}"
+    verify_host: true
+  when: pdf_files.matched > 0
+
+- name: Return PDF artifact to Zuul
+  zuul_return:
+    data:
+      zuul:
+        artifacts:
+          - name: "Docs PDF"
+            url: "pdf/{{ pdf_files.files[0].path | basename }}"
+            metadata:
+              type: docs_pdf