11 Mar, 2009
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!
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 (./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:
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!
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.
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 :members:
Copyright James Gardner 1996-2020 All Rights Reserved. Admin.