Rendering PDF from reStructuredText¶

Sphinx is using builders to produce output. The builder’s "name" must be given to the -b command-line option of sphinx-build to select a builder. For instance, when compiling as HTML, this extension invokes:

$ sphinx-build -b html -c /path/to/conf.py ...

Sphinx is able to render PDF using either LaTeX as intermediate format or rst2pdf. PDF output with rst2pdf is by far not as good as when using LaTeX but it has the real advantage of not requiring you to install a full LaTeX stack on your machine.

The builder name for PDF rendering using rst2pdf is simply pdf:

$ sphinx-build -b pdf -c /path/to/conf.py ...

whereas the builder name for LaTeX rendering is latex:

$ sphinx-build -b latex -c /path/to/conf.py ...

This latter produces a bunch of LaTeX files in the output directory. You have to specify which documents are to be included in which LaTeX files via the latex_documents configuration value. There are a few configuration values that customize the output of this builder. See chapter Options for LaTeX output for details.

Once the LaTeX files have been produced, the actual rendering as PDF is just a matter of compiling the LaTeX sources with pdflatex:

$ pdflatex name-of-project

The remainder of this chapter gives you more insights on LaTeX: