James Gardner: Home > Blog > 2009 > Sphinx PDF Generation with LaTeX

Sphinx PDF Generation with LaTeX

Posted:2009-03-11 19:51
Tags:Python, Desktop Software, Ubuntu, LaTeX

In order to be able to generate PDF and PS files from reStructuredText using LaTeX on Debian-based systems you need to install the following software:

sudo apt-get install wget build-essential python2.5-dev texlive-full

We'll use Sphinx to handle the all the complicated bits.

You need wget to get the virtualenv.py script and you need build-essential and python2.5-dev to build the C extension for Jinja, a templating language which Sphinx relies on.

Let's set up a virtual Python environment sandbox and install Sphinx into it:

$ mkdir download
$ cd download
$ wget http://pylonsbook.com/virtualenv.py
$ python2.5 virtualenv.py ../env
New python executable in ../env/bin/python2.5
Also creating executable in ../env/bin/python
Installing setuptools...........................done.
$ cd ../
$ env/bin/easy_install sphinx pygments

Now you are ready to create some test documentation. Create a directory and run the sphinx-quickstart program installed into the virtual Python environment along with Sphinx:

$ mkdir test_docs
$ cd test_docs
$ ../env/bin/sphinx-quickstart
Welcome to the Sphinx quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]:

You have two options for placing the build directory for Sphinx output.
Either, you use a directory ".build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: y

Inside the root directory, two more directories will be created; ".templates"
for custom HTML templates and ".static" for custom stylesheets and other
static files. Since the leading dot may be inconvenient for Windows users,
you can enter another prefix (such as "_") to replace the dot.
> Name prefix for templates and static dir [.]:

The project name will occur in several places in the built documentation.
> Project name: TestProject
> Author name(s): James Gardner

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 0.1
> Project release [0.1]: 0.1.1

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]: .txt

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y

If you are under Unix, a Makefile can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
> Create Makefile? (Y/n) [y]: y

Finished: An initial directory structure has been created.

You should now populate your master file ./source/index.txt and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Once the wizard has finished you need to edit the Makefile to specify the correct path to the sphinx-build command:

SPHINXBUILD   = /home/user/env/bin/sphinx-build

Now you are ready to write some reStructuredText. This chapter from the Pylons Book has some examples: http://pylonsbook.com/alpha1/documenting_a_pylons_project.

Now you can try creating LaTeX documentation:

$ make latex
mkdir -p build/latex build/doctrees
/home/user/env/bin/sphinx-build -b latex -d build/doctrees   source build/latex
Sphinx v0.5.1, building latex
loading pickled environment... done
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
processing TestProject.tex... index
resolving references...
writing... done
copying TeX support files... done
build succeeded.

Build finished; the LaTeX files are in build/latex.
Run `make all-pdf' or `make all-ps' in that directory to run these through (pdf)latex.

The build is successful, let's try and use the generated LaTeX to build a PDF:

$ cd build/latex/
$ make all-pdf
pdflatex 'TestProject.tex'
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
 %&-line parsing enabled.
entering extended mode
LaTeX2e <2005/12/01>
Babel <v3.8h> ...
Output written on TestProject.pdf (7 pages, 51346 bytes).
Transcript written on TestProject.log.

After a few lines of output you are left with a nice shiny PDF file named TestProject.pdf. You can download it here. Obviously this version isn't very exciting because no content has been added to the index.txt file but at least it has generated correctly!

You Can't Avoid Using texlive-full

If you hadn't installed the texlive-full package you would have seen this:

$ make all-pdf
pdflatex 'TestProject.tex'
make: pdflatex: Command not found
make: *** [TestProject.pdf] Error 127

If you had tried to install texlive rather than texlive-full to sae yourself 449Mb of extra downloads you'd have seen this:

$ make all-pdf
pdflatex 'TestProject.tex'
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
 %&-line parsing enabled.
entering extended mode
LaTeX2e <2005/12/01>
Babel <v3.8h> and hyphenation patterns for english, usenglishmax, dumylang, noh
yphenation, loaded.
Document Class: manual 2008/10/18 Document class (Sphinx manual)
Document Class: report 2005/09/16 v1.4f Standard LaTeX document class
(/usr/share/texmf-texlive/tex/latex/psnfss/times.sty) (./fncychap.sty)
(./sphinx.sty (/usr/share/texmf-texlive/tex/latex/base/textcomp.sty
Style option: `fancybox' v1.3 <2000/09/19> (tvz)

! LaTeX Error: File `titlesec.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)

Enter file name:

As you can see, the texlive package is missing the titlesec.sty file we need so you have to install the texlive-full package.

Update 2009-06-15: Pablo Navarro Castillo has kindly emailed me to point out that installing texlive-latex-extra fixes this problem without the need to install the whole texlive-full package. Thanks Pablo!

Generating PostScript or DVI Files

It turns out that the version of latex installed with the TeX live distribution is pdflatex which seems incapable of outputting DVI or PS files even when using the -output-format option. This is completely mad but there you go. If you want PS or DVI output you need to run a converter on the PDF file or think about using the older (and unsupported) tetex LaTeX distribution.

This all meand that the make all-dvi and make all-ps commands don't work with Sphinx.

API Documentaion - Documenting Module Members

If you are looking towards Sphinx as a replacemnt for Pudge or other API documentation tools you should take a look at the autodoc facilities. Although Sphinx isn't really an API documentation tool pre se, it can automatically generate documention from Python source code and docstrings. Try adding a document with this in it:

.. automodule:: some.module

Further Reading

See also:

(view source)

James Gardner: Home > Blog > 2009 > Sphinx PDF Generation with LaTeX