merge libmaple docs ("leaflabs-docs") into ./docs

In the past, libample documentation was forked out of this repository
because the documentation had increased in scope. For the librambutan,
and the rambutan project in general, we will try to keep documentation
closer to the source code, so the librambutan-specific documentation
should live here. Other sections of leaflabs-docs will be culled in a
following commit.

This merge attempts to maintain history by using a subtree strategy.
Followed directions at:

    http://nuclearsquid.com/writings/subtree-merging-and-you/

Full history for files should be accessible using the "--follow" flag to
git log, eg:

    git log --follow docs/source/adc.rst

It should be possible to pull patches from leaflabs-docs with:

    git pull -s subtree leaflabs-docs master

... at least until the docs in this repository diverge significantly.

1 files changed, 105 insertions, 0 deletions

diff --git a/docs/README-building.txt b/docs/README-building.txt
new file mode 100644
index 0000000..de4a7f7
--- /dev/null
+++ b/docs/README-building.txt
@@ -0,0 +1,105 @@
+This file explains how to build the HTML documentation. As such, it's
+probably only useful to LeafLabs developers. Users can read the HTML
+for the latest release here:
+
+    http://leaflabs.com/docs/
+
+Install Dependencies
+--------------------
+
+First, you will need to install some dependencies (Doxygen, Sphinx,
+and Breathe).
+
+1. Much of the documentation is pulled out of the libmaple source
+   code's Doxygen comments, so you need a recent-ish version of
+   Doxygen in your PATH:
+
+    http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
+
+2. Documentation not taken from the libmaple sources is written in
+   Sphinx's extensions to the reStructuredText (reST) markup language.
+   (More about Sphinx: http://sphinx.pocoo.org/tutorial.html).
+
+   These are your choices for how to 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.
+
+3. We use a Sphinx plugin called Breathe to parse Doxygen's XML output
+   into a form usable by Sphinx. (More about Breathe:
+   http://michaeljones.github.com/breathe/).
+
+   LeafLabs sometimes patches Breathe for the purposes of building our
+   docs, so clone the LeafLabs Breathe tree from GitHub (somewhere
+   else on your system, NOT in the leaflabs-docs repo):
+
+   - LeafLabs developers, clone with push permissions:
+     $ git clone git@github.com:leaflabs/breathe.git
+
+   - Everyone else, clone without them:
+     $ git clone git://github.com/leaflabs/breathe.git
+
+4. After that's done, set environment variables LIB_MAPLE_HOME to
+   point to libmaple, and BREATHE_HOME to point to Breathe.  Something
+   like this in Bash:
+
+   $ export LIB_MAPLE_HOME=/path/to/libmaple/repo/
+   $ export BREATHE_HOME=/path/to/breathe/repo/
+
+   (You'll want this in your shell startup script.)
+
+Build the Docs
+--------------
+
+You are finally ready to build the documentation.  First, you'll
+produce Doxygen XML output, then you can generate the final HTML docs.
+
+1. Before the first time you run Sphinx (and any time the Doxygen
+   comments in the libmaple source code are changed), you'll need to
+   re-run doxygen on libmaple.
+
+    $ cd /path/to/libmaple
+    $ make doxygen
+
+   Doxygen will yell at you a lot; it's generally safe to ignore it.
+
+2. Finally, you can build the HTML (in the leaflabs-docs repository):
+
+    $ cd /path/to/leaflabs-docs
+    $ make html
+
+   On Windows, you can supposedly use the batch file make.bat instead.
+
+   Breathe will yell at you a lot; it's often safe to ignore this,
+   too. C'est la vie.
+
+Read and Modify the Docs
+------------------------
+
+Point your web browser at the file
+
+  build/html/index.html
+
+For the most part, the file build/html/foo.html is built from
+source/foo.rst.  (The index is an exception, because we needed to
+hand-hack the HTML to get the "Contents at a Glance" section to look
+nice).
+
+All of the documentation which isn't pulled out of libmaple's Doxygen
+comments lives in source/.  The directory source/_static/ is for
+static content (like style sheets); source/_templates/ is meant to
+contain Sphinx templates.
+
+Read more about Sphinx and use the existing leaflabs-docs source for
+examples when writing new docs.  The directory tmpl/ contains template
+ReST files you should sometimes use when creating a page that follows
+a pattern (like a libmaple API page), in order to keep the style
+consistent.
+
+The file source/conf.py is the Sphinx configuration file; you can go
+read it for more information about our setup.