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
This commit is contained in:
Akihiro Motoki 2019-08-22 03:28:13 +09:00 committed by Andreas Jaeger
parent b9d47e5f6a
commit bba1a617ee
9 changed files with 106 additions and 1 deletions

View File

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

View File

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

View File

@ -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.

View File

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

View File

@ -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

View File

@ -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.

View File

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

View File

@ -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

View File

@ -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