From bba1a617eefff6f7f2f34c1ea6154816233dc627 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Thu, 22 Aug 2019 03:28:13 +0900 Subject: [PATCH] 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 Co-Authored-By: Andreas Jaeger Depends-On: https://review.opendev.org/678077 Change-Id: Ibc455ba511a877159848f4060a6058800d7d2f9b --- playbooks/tox-docs/pre.yaml | 4 +++ playbooks/tox-docs/run.yaml | 7 +++++ roles/build-pdf-docs/README.rst | 16 ++++++++++++ roles/build-pdf-docs/defaults/main.yaml | 2 ++ roles/build-pdf-docs/tasks/main.yaml | 11 ++++++++ roles/prepare-build-pdf-docs/README.rst | 20 ++++++++++++++ .../prepare-build-pdf-docs/defaults/main.yaml | 2 ++ roles/prepare-build-pdf-docs/tasks/main.yaml | 19 ++++++++++++++ zuul.d/jobs.yaml | 26 ++++++++++++++++++- 9 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 playbooks/tox-docs/pre.yaml create mode 100644 playbooks/tox-docs/run.yaml create mode 100644 roles/build-pdf-docs/README.rst create mode 100644 roles/build-pdf-docs/defaults/main.yaml create mode 100644 roles/build-pdf-docs/tasks/main.yaml create mode 100644 roles/prepare-build-pdf-docs/README.rst create mode 100644 roles/prepare-build-pdf-docs/defaults/main.yaml create mode 100644 roles/prepare-build-pdf-docs/tasks/main.yaml diff --git a/playbooks/tox-docs/pre.yaml b/playbooks/tox-docs/pre.yaml new file mode 100644 index 00000000..3b8e28ed --- /dev/null +++ b/playbooks/tox-docs/pre.yaml @@ -0,0 +1,4 @@ +- hosts: all + roles: + - role: prepare-build-pdf-docs + when: not tox_skip_pdf diff --git a/playbooks/tox-docs/run.yaml b/playbooks/tox-docs/run.yaml new file mode 100644 index 00000000..88e6ec6e --- /dev/null +++ b/playbooks/tox-docs/run.yaml @@ -0,0 +1,7 @@ +- hosts: all + roles: + - revoke-sudo + - tox + - role: build-pdf-docs + when: not tox_skip_pdf + diff --git a/roles/build-pdf-docs/README.rst b/roles/build-pdf-docs/README.rst new file mode 100644 index 00000000..504ae827 --- /dev/null +++ b/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. diff --git a/roles/build-pdf-docs/defaults/main.yaml b/roles/build-pdf-docs/defaults/main.yaml new file mode 100644 index 00000000..f6dcf373 --- /dev/null +++ b/roles/build-pdf-docs/defaults/main.yaml @@ -0,0 +1,2 @@ +zuul_work_dir: "{{ zuul.project.src_dir }}" +tox_pdf_envlist: pdf-docs diff --git a/roles/build-pdf-docs/tasks/main.yaml b/roles/build-pdf-docs/tasks/main.yaml new file mode 100644 index 00000000..95e44cc4 --- /dev/null +++ b/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 diff --git a/roles/prepare-build-pdf-docs/README.rst b/roles/prepare-build-pdf-docs/README.rst new file mode 100644 index 00000000..7c7f2560 --- /dev/null +++ b/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. diff --git a/roles/prepare-build-pdf-docs/defaults/main.yaml b/roles/prepare-build-pdf-docs/defaults/main.yaml new file mode 100644 index 00000000..53252063 --- /dev/null +++ b/roles/prepare-build-pdf-docs/defaults/main.yaml @@ -0,0 +1,2 @@ +zuul_work_dir: "{{ zuul.project.src_dir }}" +pdf_tox_envlist: pdf-docs diff --git a/roles/prepare-build-pdf-docs/tasks/main.yaml b/roles/prepare-build-pdf-docs/tasks/main.yaml new file mode 100644 index 00000000..7d1c0c30 --- /dev/null +++ b/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 diff --git a/zuul.d/jobs.yaml b/zuul.d/jobs.yaml index e2abcea0..af703f48 100644 --- a/zuul.d/jobs.yaml +++ b/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