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:
parent
b9d47e5f6a
commit
bba1a617ee
|
@ -0,0 +1,4 @@
|
|||
- hosts: all
|
||||
roles:
|
||||
- role: prepare-build-pdf-docs
|
||||
when: not tox_skip_pdf
|
|
@ -0,0 +1,7 @@
|
|||
- hosts: all
|
||||
roles:
|
||||
- revoke-sudo
|
||||
- tox
|
||||
- role: build-pdf-docs
|
||||
when: not tox_skip_pdf
|
||||
|
|
@ -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.
|
|
@ -0,0 +1,2 @@
|
|||
zuul_work_dir: "{{ zuul.project.src_dir }}"
|
||||
tox_pdf_envlist: pdf-docs
|
|
@ -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
|
|
@ -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.
|
|
@ -0,0 +1,2 @@
|
|||
zuul_work_dir: "{{ zuul.project.src_dir }}"
|
||||
pdf_tox_envlist: pdf-docs
|
|
@ -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
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue