This project is now maintained in the Python SVN at svn.python.org/projects/doctools.
This sandbox project is about moving the official Python documentation to reStructuredText.
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.
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.
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.