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. 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. 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.