sphinx / README

Full commit
doctools README

What you need to know

This project uses Python 2.5 features, so you'll need a working Python
2.5 setup.  Docutils 0.4 is required, the Docutils SVN trunk does not
work at the moment, but I don't expect it to be difficult to fix that.

Docutils can be installed from the PyPI (Cheese Shop) via ``easy_install``
or from

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

Converting the LaTeX sources

**This paragraph is obsolete.**  The conversion has been done, and reST docs
trees are now maintained for 2.6 and 3.0 branches.

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 -- the SVN URL for readonly
access is 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

   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 ~/devel/python/Doc sources

This will convert all LaTeX sources to reST files in the ``sources``

The ``sources`` directory contains a ```` 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"

Building the HTML version

Then, create a target directory and run ::

   mkdir build-html
   python -b html Doc-26 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 -b web Doc-26 build-web

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

Then, you can run ::

   python build-web

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

Writing new documentation

The new "Documenting Python" document, contained in a converted documentation
tree, already lists most of the markup and features, both standard reST and
additional, that can be used in the source docs.

More reST docs are at, tutorials can be found on
the web.