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