1 files changed, 83 insertions, 0 deletions
diff --git a/docs/README b/docs/README
new file mode 100644
index 0000000..326d278
--- /dev/null
+++ b/docs/README
@@ -0,0 +1,83 @@
+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.