Building PDFs for OpenStack documentation

I’ve only ever really worked with HTML and man page builds for the documentation various of various OpenStack projects. However, OpenStack uses Sphinx across the board and Sphinx, being the awesome tool that it is, supports many other output formats. In this instance, I was interested in PDF.

Sphinx doesn’t actually provide a native PDF builder (although other packages do). Instead, you have to generate LaTeX sources and then generate a PDF for this. This means you need to have a pretty well fleshed out TeX installation. As such, the first step is to install the dependencies.

Install dependencies

We need a number of packages to build the LaTeX sources and convert them into a PDF. I’m using Fedora 27 which means package names may need to be adjusted accordingly. Do note, however, that these names should work equally well on RHEL and RHEL derivatives like CentOS).

• texlive (TeX Live)

  Per the description of this package in the Fedora repos.

  The TeX Live software distribution offers a complete TeX system for a variety of Unix, Macintosh, Windows and other platforms. It encompasses programs for editing, typesetting, previewing and printing of TeX documents in many different languages, and a large collection of TeX macros and font libraries.

  The distribution includes extensive general documentation about TeX, as well as the documentation for the included software packages.

  This is the basic thing we need to actually build LaTeX documents and convert them to PDF. The package itself includes multiple other dependencies, either because they are necessary for a minimal install or they form a standard library of sorts. I’m not sure which.

• latexmk

  Per the description of this package in the Fedora repos.

  latexmk is a perl script for running LaTeX the correct number of times to resolve cross references, etc.; it also runs auxiliary programs (bibtex, makeindex if necessary, and dvips and/or a previewer as requested). It has a number of other useful capabilities, for example to start a previewer and then run latex whenever the source files are updated, so that the previewer gives an up-to-date view of the document. The script runs on both UNIX and MS-WINDOWS (95, ME, XP, etc). This script is a corrected and improved version of the original version of latexmk.

  This is a tool that Sphinx uses, via some makefiles it includes with the built sources to ease converting the built LaTeX sources into PDFs.

You also need a variety of other packages which aren’t included as part of the texlive installation. The base Sphinx template has the following requirements.

• texlive-fncychap
• texlive-titlesec
• texlive-tabulary
• texlive-framed
• texlive-wrapfig
• texlive-upquote
• texlive-capt-of
• texlive-needspace

In addition, openstackdocstheme, the theme used for all official OpenStack projects, provides a LaTeX template with the following dependencies.

• texlive-polyglossia

Installation of all the above.

$ sudo dnf install texlive latexmk texlive-fncychap texlive-titlesec \
    texlive-tabulary texlive-framed texlive-wrapfig texlive-upquote \
    texlive-capt-of texlive-needspace texlive-polyglossia

Get some documentation

I didn’t have specific project in mind, so I’ve decided to build the project documentation for the openstackdocstheme project. As mentioned previously, this project provides the theme used for all Official OpenStack projects. Given that this is the base for most projects’ documentation, it figures that it contains all the necessary configuration to build PDFs. If, however, you are planning to build docs for some other project, you should ensure that this is project is configured correctly for PDF builds.

To begin, clone the repo locally.

$ git clone https://github.com/openstack/openstackdocstheme

Once cloned, create a virtual environment and install the dependencies.

$ virtualenv .venv
$ source .venv
$ pip install -e .

In the case of openstackdocstheme, Sphinx isn’t installed by default. Let’s install that too.

$ pip install Sphinx

Build the docs

Now that we have both our dependencies and source documentation in place, it’s time to actually build some PDFs. Sphinx actually provides a number of helpful targets in the Makefile generated by sphinx-quickstart. However, OpenStack projects don’t tend to use these so we’re going to take the (still exceedingly simple) two-step process. Firstly, build the LaTeX sources. Seeing as this is a Python project, we’re going to use the setuptools integration.

$ python setup.py build_sphinx -b latex

All OpenStack projects place their documentation source and builds in doc/source and doc/build respectively. The above command should generate a number of files in doc/build/latex including a very helpful makefile. We’re going to use that now to complete the process of generating a PDF.

$ make -C doc/build/latex

This should emit a lot of text, followed by something that looks like this.

Output written on os-doc-demo.pdf (23 pages).
Transcript written on os-doc-demo.log.
=== TeX engine is 'XeTeX'
Latexmk: Index file 'os-doc-demo.idx' was written
Latexmk: Log file says output to 'os-doc-demo.pdf'
Latexmk: All targets (os-doc-demo.pdf) are up-to-date

Once complete, you can find your compiled PDF in the same build directory (in this case, doc/build/latex/os-doc-demo.pdf)