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

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


What you need to know
---------------------

As prerequisites, you need Pygments >= 0.8 and Jinja >= 1.1, easily
installable from PyPI. The former is used as the highlighter, the latter
is the templating engine for HTML output.

To convert the LaTeX doc to reST, create a target directory for the
reST sources and run ::

   python convert.py /path/to/checkout/Doc /path/to/rest/dir

This will convert all LaTeX sources to reST files in the target directory.

Note: the ``inst`` document ("Installing Python Modules") is only
convertable after applying the patch in ``etc/inst.diff``.

Then, create a target directory and run ::

   python sphinx-build.py /path/to/rest/dir /path/to/target/dir

This will create HTML files in the target directory.


Running the online (web) version
--------------------------------

First, you need to build the source with the "web" builder::

   python sphinx-build.py -b web /path/to/rest/dir /path/to/target/dir

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

Then, you can run ::

   python sphinx-web.py /path/to/target/dir

which will serve the documentation using wsgiref on localhost:3000.


Things That Should Be Improved
------------------------------

-  Offline and online search work completely different. The
   keywords are just searched from the sidebar and other
   incompatibilities. It's also questionable if a text search
   like the current implementation makes sense for the documentation.
