Add support for building PDFs

We want PDFs. We don't want to have to go to each project and add a
'pdf' tox target or similar. Get the former and avoid the latter by
adding a step to build our PDFs to the 'openstack-tox-docs' job.

The job assumes a 'pdf-docs' tox env to build PDF docs.
If 'pdf-docs' tox env does not exist, PDF doc build will be skipped.

Note that only the job for master and stein is updated,
we do not build PDFs for older releases.

Do not build PDFs for deploy-guide for now.

Co-Authored-By: Stephen Finucane <stephenfin@redhat.com>
Co-Authored-By: Andreas Jaeger <aj@suse.com>
Depends-On: https://review.opendev.org/678077
Change-Id: Ibc455ba511a877159848f4060a6058800d7d2f9b

playbooks/tox-docs/pre.yaml

@@ -0,0 +1,4 @@
+- hosts: all
+  roles:
+    - role: prepare-build-pdf-docs
+      when: not tox_skip_pdf

playbooks/tox-docs/run.yaml

@@ -0,0 +1,7 @@
+- hosts: all
+  roles:
+    - revoke-sudo
+    - tox
+    - role: build-pdf-docs
+      when: not tox_skip_pdf
+

roles/build-pdf-docs/README.rst

@@ -0,0 +1,16 @@
+Build PDFs from sphinx documents
+
+If the tox environment specified in `tox_pdf_envlist`
+does not exist, the PDF build will be skipped.
+
+**Role Variables**
+
+.. zuul:rolevar:: tox_pdf_envlist
+   :default: pdf-docs
+
+   The tox environment used for PDF doc build.
+
+.. zuul:rolevar:: zuul_work_dir
+   :default: {{ zuul.project.src_dir }}
+
+   The location of the main working directory of the job.

roles/build-pdf-docs/defaults/main.yaml

@@ -0,0 +1,2 @@
+zuul_work_dir: "{{ zuul.project.src_dir }}"
+tox_pdf_envlist: pdf-docs

roles/build-pdf-docs/tasks/main.yaml

@@ -0,0 +1,11 @@
+- name: Check tox env for PDF build in tox.ini
+  shell: |
+    grep '^\[testenv:{{ tox_pdf_envlist }}\]' {{ zuul_work_dir }}/tox.ini
+  register: pdfdocs_env
+  ignore_errors: yes
+
+- include_role:
+    name: tox
+  vars:
+    tox_envlist: "{{ tox_pdf_envlist }}"
+  when: pdfdocs_env is success

roles/prepare-build-pdf-docs/README.rst

@@ -0,0 +1,20 @@
+Install Packages for build-pdf-docs
+
+Install binary packages for :zuul:role:`build-pdf-docs`.
+
+This role currently only supports Ubuntu Bionic.
+
+If the tox environment specified in `tox_pdf_envlist`
+does not exist, package installation will be skipped.
+
+**Role Variables**
+
+.. zuul:rolevar:: tox_pdf_envlist
+   :default: pdf-docs
+
+   The tox environment used for PDF doc building.
+
+.. zuul:rolevar:: zuul_work_dir
+   :default: {{ zuul.project.src_dir }}
+
+   The location of the main working directory of the job.

roles/prepare-build-pdf-docs/defaults/main.yaml

@@ -0,0 +1,2 @@
+zuul_work_dir: "{{ zuul.project.src_dir }}"
+pdf_tox_envlist: pdf-docs

roles/prepare-build-pdf-docs/tasks/main.yaml

@@ -0,0 +1,19 @@
+- name: Check tox env for PDF build in tox.ini
+  shell: |
+    grep '^\[testenv:{{ tox_pdf_envlist }}\]' {{ zuul_work_dir }}/tox.ini
+  register: pdfdocs_env
+  ignore_errors: yes
+
+- name: Install PDF prereqs
+  package:
+    name:
+      - latexmk
+      - texlive-xetex
+      - texlive-fonts-recommended
+      - fonts-liberation
+      - inkscape
+      # Required by sphinxcontrib-svg2pdfconverter to handle SVG images
+      - librsvg2-bin
+    state: present
+  become: yes
+  when: pdfdocs_env is success

zuul.d/jobs.yaml

@@ -403,13 +403,36 @@
       Run documentation build.
 
       Uses tox with the ``docs`` environment.
+
+      .. zuul:jobvar: tox_envlist
+
+         The tox environment for building HTML, default is ``docs``.
+
+      .. zuul:jobvar: tox_pdf_envlist
+
+         The tox environment for building PDF, default is ``pdf-docs``.
+         If this enironment does not exist, no PDF building is done.
+
+      .. zuul:jobvar: tox_skip_pdf
+
+         Whether to skip building of PDF documents. By default a PDF
+         file is build if the tox environment specified by
+         :zuul:jobvar:`tox_pdf_envlist` exists.
+
     branches: ^(?!stable/(ocata|pike|queens|rocky)).*$
     required-projects:
       - name: openstack/requirements
     vars:
       tox_constraints_file: '{{ ansible_user_dir }}/src/opendev.org/openstack/requirements/upper-constraints.txt'
-      tox_envlist: docs
       bindep_profile: compile doc
+      tox_envlist: docs
+      tox_pdf_envlist: pdf-docs
+      tox_skip_pdf: false
+    # PDF Building is only done from stein onwards, therefore these
+    # pre-run and run playbooks are not part of the other
+    # openstack-tox-docs job.
+    pre-run: playbooks/tox-docs/pre.yaml
+    run: playbooks/tox-docs/run.yaml
     success-url: html/
 
 - job:
@@ -663,6 +686,7 @@
     vars:
       sphinx_build_dir: deploy-guide/build
       tox_envlist: deploy-guide
+      tox_skip_pdf: true
 
 - job:
     name: build-openstack-install-guide