doctools README
===============

FIXME: This is already outdated since the conversion has happened and the
reST sources are in the Python tree now.

TODO: update this.


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 http://docutils.sourceforge.net/.

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 http://svn.python.org/projects/python/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 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 sphinx-build.py -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 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.


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 http://docutils.sf.net/rst.html, tutorials can be found on
the web.