This directory contains the Sphinx documentation for libmaple, as well
as a Doxygen configuration file; we turn Doxygen XML output into
Sphinx documentation.  You can generate HTML documentation using the
Makefile if you have make, or using make.bat from Windows.

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

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

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
   rebuild the Doxygen XML output:

    $ cd libmaple/docs/source
    $ doxygen

5. Finally, you can build the documentation:

    $ make html

   (Read the Makefile for more targets).

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

The net effect of the above is to produce Doxygen XML output (ignore
this) in libmaple/docs/doxygen/xml, and HTML documentation (this is
what you want) in libmaple/docs/build/html.

Just point your web browser at the file

  libmaple/docs/build/html/index.html

it corresponds to the Sphinx file

  libmaple/docs/source/index.rst

All of the documentation itself lives in libmaple/docs/source/.  The
directory source/_static/ is for static content (like style sheets);
source/_templates/ contains Sphinx templates (or, it would, if we had
any).

The docs are written in Sphinx's version of reStructuredText (reST);
it's a Python thing that they use to produce the docs at
http://python.org.  You can read more about Sphinx here:

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

You can view the source for any generated page of documentation by
clicking the "Show Source" link in the sidebar.

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