Initial import of the doc tools.

1 files changed, 79 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 00000000..9cf2e75c
--- /dev/null
+++ b/README
@@ -0,0 +1,79 @@
+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.
+