Build PDF docs from rst-based guide documents

Build PDF docs from rst-based guide documents

https://blueprints.launchpad.net/openstack-manuals/+spec/build-pdf-from-rst-guides

Generating PDF doc files for current openstack-manuals documents and providing PDF download URLs to each HTML document is helpful for users who want to see documents offline.

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.

Alternatives

  • Building PDFs separately (without using current Sphinx build scripts) can be an alternative. However, this result will decrease the manageability of build scripts in documentation repositories.
  • Document how users can built PDFs locally but do not publish PDFs.
  • Leave the guide with current HTML build infrastructure as is.

Implementation

Assignee(s)

  • ianychoi
  • nexusz99
  • jangpro2
  • raymon-ha
  • seungkyua
  • sungjin

Work Items

  • Identifying requirements of libraries
  • Checking the compatibility of the libraries
  • Changes in Sphinx configuration
  • A basic PDF theme (fancy theme design is not the main goal)
    • Suggested minimums
      • title page
      • accurate page numbers
      • table of contents entries and links to H1, H2 from TOC
      • inline images are kept inside page print margins
      • tables wrap appropriately for page print margins
      • print target is standard size (e.g., 8.5x11 or A4)
      • grey or light color background for any code output for those who do print to save on ink/toner
      • open source font selections
      • file name does not contain spaces or special characters
  • Integrating building PDF jobs with current tox HTML build environment
  • Applying PDF build functionalities to all HTML documents in openstack-manuals repository

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.
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

docs-specs