This directory contains source files used to generate libmaple's
documentation.  

The generated documentation for the latest libmaple release is
available online in HTML form at http://leaflabs.com/docs/.  The web
interface is the recommended way for users to read the documentation.

This file contains instructions for generating the HTML files.

About the Documentation
-----------------------

The docs are written in Sphinx's extensions to reStructuredText
(reST).  You can read more about Sphinx here:

    http://sphinx.pocoo.org/tutorial.html

Much of the documentation is pulled out of the libmaple source code;
we use Doxygen XML output into Sphinx documentation.  You can read
more about Doxygen here:

    http://doxygen.org

We use a Sphinx plugin called Breathe to parse Doxygen's XML output
into a form usable by Sphinx.  You can read more about Breathe here:

    http://michaeljones.github.com/breathe/

Documentation Build Steps
-------------------------

You first need to produce Doxygen XML output, then you can generate
the HTML documentation.

1. You need a recent-ish version of Doxygen in your PATH:

    http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

2. Install Breathe, which does Doxygen-to-Sphinx conversion:

   Read/write version (for LeafLabs developers):

    $ git clone git@github.com:leaflabs/breathe.git

   Read-only version (for non-LeafLabs developers):

    $ git clone git://github.com/leaflabs/breathe.git

   After that's done, set an environment variable BREATHE_HOME to
   point to where you downloaded it.  Something like this on bash:

    $ export BREATHE_HOME=/path/to/breathe/repo/

   (You'll want to put this in your shell startup script).

3. Install Sphinx.

   From source or .egg:

    http://pypi.python.org/pypi/Sphinx#downloads

   Via easy_install:

    $ sudo easy_install -U Sphinx

   You need Sphinx version >= 1.0.6.

4. Before the first time you run Sphinx (and any time the Doxygen
   comments in the libmaple source code are changed), you'll need to
   build the Doxygen XML output:

    $ cd libmaple/docs/source
    $ doxygen

5. Finally, you can build the documentation:

    $ make html

   On Windows, use the batch file make.bat instead.

Reading and Modifying the Documentation
---------------------------------------

Just point your web browser at the file

  /docs/build/html/index.html

It corresponds to the Sphinx file

  /docs/source/index.rst

The file /docs/source/conf.py is the Sphinx configuration file; you
can go read it for more information about our setup.

All of the documentation which isn't pulled out of source code
comments lives in /docs/source/.  The directory /docs/source/_static/
is for static content (like style sheets); /docs/source/_templates/
contains Sphinx templates.