sandbox/py-rest-doc/README

   1 OUT OF DATE
   2 ===========
   3
   4 This project is now maintained in the Python SVN at svn.python.org/projects/doctools.
   5
   6
   7 py-rest-doc
   8 ===========
   9
  10 This sandbox project is about moving the official Python documentation
  11 to reStructuredText.
  12
  13
  14 What you need to know
  15 ---------------------
  16
  17 This project uses Python 2.5 features, so you'll need a working Python
  18 2.5 setup.
  19
  20 If you want code highlighting, you need Pygments >= 0.8, easily
  21 installable from PyPI.  Jinja, the template engine, is included as a
  22 SVN external.
  23
  24 For the rest of this document, let's assume that you have a Python
  25 checkout (you need the 2.6 line, i.e. the trunk) in ~/devel/python and
  26 this checkout in the current directory.
  27
  28 To convert the LaTeX doc to reST, you first have to apply the patch in
  29 ``etc/inst.diff`` to the ``inst/inst.tex`` LaTeX file in the Python
  30 checkout::
  31
  32    patch -d ~/devel/python/Doc -p0 < etc/inst.diff
  33
  34 Then, create a target directory for the reST sources and run the
  35 converter script::
  36
  37    mkdir sources
  38    python convert.py ~/devel/python/Doc sources
  39
  40 This will convert all LaTeX sources to reST files in the ``sources``
  41 directory.
  42
  43 The ``sources`` directory contains a ``conf.py`` file which contains
  44 general configuration for the build process, such as the Python
  45 version that should be shown, or the date format for "last updated on"
  46 notes.
  47
  48
  49 Building the HTML version
  50 -------------------------
  51
  52 Then, create a target directory and run ::
  53
  54    mkdir build-html
  55    python sphinx-build.py -b html sources build-html
  56
  57 This will create HTML files in the ``build-html`` directory.
  58
  59 The ``build-html`` directory will also contain a ``.doctrees``
  60 directory, which caches pickles containing the docutils doctrees for
  61 all source files, as well as an ``environment.pickle`` file that
  62 collects all meta-information and data that's needed to
  63 cross-reference the sources and generate indices.
  64
  65
  66 Running the online (web) version
  67 --------------------------------
  68
  69 First, you need to build the source with the "web" builder::
  70
  71    mkdir build-web
  72    python sphinx-build.py -b web sources build-web
  73
  74 This will create files with pickled contents for the web application
  75 in the target directory.
  76
  77 Then, you can run ::
  78
  79    python sphinx-web.py build-web
  80
  81 which will start a webserver using wsgiref on ``localhost:3000``.  The
  82 web application has a configuration file ``build-web/webconf.py``,
  83 where you can configure the server and port for the application as
  84 well as different other settings specific to the web app.
  85