OUT OF DATE
===========

This project is now maintained in the Python SVN at svn.python.org/projects/doctools.


py-rest-doc
===========

This sandbox project is about moving the official Python documentation
to reStructuredText.


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.