Switch PDF fetching to known files

Some repos produce intermediate PDF files, for example from svg files,
and thus we have multiple PDF files.

Change the PDF fetching to a list of pdf_files which can be supplied,
the default is the name of the repos with ".pdf" attached, like
"octavia.pdf".

https://review.opendev.org/#/c/667249/3 illustrates the problem.

Change-Id: I5d3b6d6c2884ba66bdd35639b023d6d76f64ac01

roles/fetch-sphinx-tarball/README.rst

@@ -16,3 +16,10 @@ archive into the log root for viewing.
    :default: {{ zuul.project.src_dir }}
 
    The location of the main working directory of the job.
+
+.. zuul:rolevar:: sphinx_pdf_files
+   :default: list
+
+   A list of file names of PDF files to collect.
+   By default, the list contains as entry only
+   ``{{ zuul.project.short_name }}.pdf``.

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

@@ -1,3 +1,5 @@
 ---
 zuul_work_dir: "{{ zuul.project.src_dir }}"
 sphinx_build_dir: doc/build
+sphinx_pdf_files:
+  - "{{ zuul.project.short_name }}.pdf"

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

@@ -1,44 +1,56 @@
-# Sphinx builds a single PDF, the name of the PDF is not known.
+# Sphinx might build multiple PDF files, for example for graphic files
-# Let's be safe and accept multiple PDFs but only return the first
+# to include. We only want to grab the end result and not any such
-# one.
+# input files.
 
-- name: Search PDF files under sphinx build directory
+- name: Check for PDF file names
-  find:
+  stat:
-    paths: "{{ zuul_work_dir }}/{{ sphinx_build_dir }}/pdf/"
+    path: "{{ zuul_work_dir }}/{{ sphinx_build_dir }}/pdf/{{ item }}"
-    file_type: file
+    get_checksum: false
-    patterns: "*.pdf"
+    get_mime: false
-  register: pdf_files
+    get_md5: false
+  with_items: "{{ sphinx_pdf_files }}"
+  register: pdf_file_stat
 
-- name: Report no PDF to be uploaded
+- name: Set pdf_files_found to default
-  debug:
+  set_fact:
-    msg: "Found no PDF to upload"
+    pdf_files_found: false
-  when: pdf_files.matched == 0
 
-- name: Check for single PDF
+- name: Check if any file found
-  debug:
+  set_fact:
-    msg: "Multiple PDF found, only grabbing first one"
+    pdf_files_found: true
-  when: pdf_files.matched > 1
+  when: item.stat.exists
+  with_items: "{{ pdf_file_stat.results }}"
 
-- name: Create PDF directory
+# Now loop...
-  delegate_to: localhost
-  file:
-    path: "{{ zuul.executor.log_root }}/pdf"
-    state: directory
 
-- name: Fetch PDF files
+- name: Grab PDF files
-  synchronize:
+  when: pdf_files_found
-    dest: "{{ zuul.executor.log_root }}/pdf/{{ pdf_files.files[0].path | basename }}"
+  block:
-    mode: pull
-    src: "{{ pdf_files.files[0].path }}"
-    verify_host: true
-  when: pdf_files.matched > 0
 
-- name: Return PDF artifact to Zuul
+    - name: Create PDF directory
-  zuul_return:
+      delegate_to: localhost
-    data:
+      file:
-      zuul:
+        path: "{{ zuul.executor.log_root }}/pdf"
-        artifacts:
+        state: directory
-          - name: "Docs PDF"
+
-            url: "pdf/{{ pdf_files.files[0].path | basename }}"
+    - name: Fetch PDF files
-            metadata:
+      synchronize:
-              type: docs_pdf
+        dest: "{{ zuul.executor.log_root }}/pdf/{{ item.item }}"
+        mode: pull
+        src: "{{ item.stat.path }}"
+        verify_host: true
+      with_items: "{{ pdf_file_stat.results }}"
+      when: item.stat.exists
+
+
+    - name: Return PDF artifact to Zuul
+      zuul_return:
+        data:
+          zuul:
+            artifacts:
+              - name: "Docs PDF: {{ item.item }}"
+                url: "pdf/{{ item.item }}"
+                metadata:
+                  type: docs_pdf
+      with_items: "{{ pdf_file_stat.results }}"
+      when: item.stat.exists