Build PDF docs from rst-based guide documents¶

Problem description¶

DocBook XMLs have been successfully migrated and converted into RST sources. OpenStack RST-sourced documentation uses Sphinx to build HTML documents and publish them on docs.openstack.org. And openstackdocstheme is responsible for the theme and extension in the published HTML documents.

One desired functionality in RST-sourced documents is to have PDF versions of the books. Current HTML documents are surely helpful, but having PDF versions provides OpenStack documentation readers with more additional benefits. For example, users can download PDF files and read them offline. To print HTML documents, users do more manual steps such as moving from one page to other pages and the printed layout is different from what users see through monitors. Furthermore, it is easier for users to share their personal notes in PDF files with other readers. One more advantage using PDF files is that PDF files have pages. It is useful for offline training environment with printable OpenStack documents by indicating page numbers.

Proposed change¶

Add the support of building PDFs using current Sphinx build infrastructure using RST-sourced files in openstack-manuals repository.

Generating PDF files using RST-sourced files includes two steps in workflow. First, Sphinx generates LaTeX files (.tex) from RST-sourced files. Second, pdflatex generates PDF files from generated LaTeX files.

After the combination of Sphinx and LaTeX supports PDF file generation, apply PDF buildings to all the HTML documents in openstack-manuals repository using LaTeX PDF generation. And add the build job to work with HTML builds, publish PDF files on docs.openstack.org per each document build, and finally insert PDF download URLs in the landing page of HTML documents.

Note that the main change will happen in openstack-doc-tools for scripts, openstackdocstheme for possible additional themes for PDFs, and each documentation repository such as openstack-manuals to add PDF build support in Sphinx configurations.

Implementation¶

Project Scope¶

• This spec mainly focuses on applying to documents in openstack-manuals repository. security-doc and api-site are also good targets for building PDFs, but they are out of scope in this spec.

• The support of building PDFs from translated documents is out of scope.

• For a basic PDF theme, the following requirements are out of scope.

  • Index with page numbers
  • OpenStack logo display on title page (choosing which logo is appropriate for each deliverable would get tedious)
  • Optional: watermark to indicate draft or to which version the document applies

Dependencies¶

• Can be dependent on pdf build program (e.g., LaTeX)

Testing¶

• Testing of the tools will be done as part of the builds.
• Beta-reading period on PDF files and feedback will be helpful for checking layout problems such as less image resolution and table display problems.

References¶

• http://lists.openstack.org/pipermail/openstack-docs/2016-July/008867.html
• http://lists.openstack.org/pipermail/openstack-docs/2016-July/008869.html
• https://review.openstack.org/#/c/396943/