Add build-pdf-docs and prepare-build-pdf-docs

Author: mnasiadka

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,26 @@
+- 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: Run tox with pdf build envlist
+  include_role:
+    name: tox
+  vars:
+    tox_envlist: "{{ tox_pdf_envlist }}"
+    # We run tox against the envlist without running tests so that we can
+    # control how the tox output is handled. PDF generations tends to be
+    # incredibly verbose and we don't want those logs going to the console.
+    tox_extra_args: "-vv --notest"
+  when: pdfdocs_env is success
+
+- name: Run tox with output redirected to a file
+  args:
+    chdir: "{{ zuul_work_dir }}"
+  environment: "{{ tox_environment | combine(tox_constraints_env | default({})) }}"
+  shell: |
+    echo "Running {{ tox_executable }} -e {{ tox_pdf_envlist }} -vv > {{ ansible_user_dir }}/zuul-output/logs/sphinx-build-pdf.log 2>&1"
+    echo "Output is redirected to a file as it tends to be quite verbose."
+    {{ tox_executable }} -e {{ tox_pdf_envlist }} -vv > {{ ansible_user_dir }}/zuul-output/logs/sphinx-build-pdf.log 2>&1
+  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,24 @@
+- 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
+      # Required for tgtermes.sty style, this is a recommended package
+      # for texlive-fonts-recommended but it is not installed by default.
+      - tex-gyre
+      - cm-super
+      - fonts-liberation
+      - inkscape
+      - xindy
+      # Required by sphinxcontrib-svg2pdfconverter to handle SVG images
+      - librsvg2-bin
+    state: present
+  become: yes
+  when: pdfdocs_env is success