Index of /sandbox/py-rest-doc

What you need to know

This project uses Python 2.5 features, so you'll need a working Python 2.5 setup.

If you want code highlighting, you need Pygments >= 0.8, easily installable from PyPI. Jinja, the template engine, is included as a SVN external.

For the rest of this document, let's assume that you have a Python checkout (you need the 2.6 line, i.e. the trunk) in ~/devel/python and this checkout in the current directory.

To convert the LaTeX doc to reST, you first have to apply the patch in etc/inst.diff to the inst/inst.tex LaTeX file in the Python checkout:

patch -d ~/devel/python/Doc -p0 < etc/inst.diff

Then, create a target directory for the reST sources and run the converter script:

mkdir sources
python convert.py ~/devel/python/Doc sources

This will convert all LaTeX sources to reST files in the sources directory.

The sources directory contains a conf.py file which contains general configuration for the build process, such as the Python version that should be shown, or the date format for "last updated on" notes.

Building the HTML version

Then, create a target directory and run

mkdir build-html
python sphinx-build.py -b html sources build-html

This will create HTML files in the build-html directory.

The build-html directory will also contain a .doctrees directory, which caches pickles containing the docutils doctrees for all source files, as well as an environment.pickle file that collects all meta-information and data that's needed to cross-reference the sources and generate indices.

Running the online (web) version

First, you need to build the source with the "web" builder:

mkdir build-web
python sphinx-build.py -b web sources build-web

This will create files with pickled contents for the web application in the target directory.

Then, you can run

python sphinx-web.py build-web

which will start a webserver using wsgiref on localhost:3000. The web application has a configuration file build-web/webconf.py, where you can configure the server and port for the application as well as different other settings specific to the web app.