Sphinx PDF Generation with 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
directly.
> 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
(./TestProject.tex
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!

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

$ 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
(./TestProject.tex
LaTeX2e <2005/12/01>
Babel <v3.8h> and hyphenation patterns for english, usenglishmax, dumylang, noh
yphenation, loaded.
(./manual.cls
Document Class: manual 2008/10/18 Document class (Sphinx manual)
(/usr/share/texmf-texlive/tex/latex/base/report.cls
Document Class: report 2005/09/16 v1.4f Standard LaTeX document class
(/usr/share/texmf-texlive/tex/latex/base/size10.clo)))
(/usr/share/texmf-texlive/tex/latex/base/inputenc.sty
(/usr/share/texmf-texlive/tex/latex/base/utf8.def
(/usr/share/texmf-texlive/tex/latex/base/t1enc.dfu)
(/usr/share/texmf-texlive/tex/latex/base/ot1enc.dfu)
(/usr/share/texmf-texlive/tex/latex/base/omsenc.dfu)))
(/usr/share/texmf-texlive/tex/latex/base/fontenc.sty
(/usr/share/texmf-texlive/tex/latex/base/t1enc.def))
(/usr/share/texmf-texlive/tex/generic/babel/babel.sty
(/usr/share/texmf-texlive/tex/generic/babel/english.ldf
(/usr/share/texmf-texlive/tex/generic/babel/babel.def)))
(/usr/share/texmf-texlive/tex/latex/psnfss/times.sty) (./fncychap.sty)
(./sphinx.sty (/usr/share/texmf-texlive/tex/latex/base/textcomp.sty
(/usr/share/texmf-texlive/tex/latex/base/ts1enc.def
(/usr/share/texmf-texlive/tex/latex/base/ts1enc.dfu)))
(/usr/share/texmf-texlive/tex/latex/fancyhdr/fancyhdr.sty)
(/usr/share/texmf-texlive/tex/latex/seminar/fancybox.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:

.. automodule:: some.module
   :members:

(view source)