more docs

1 files changed, 29 insertions, 12 deletions

diff --git a/docs/README b/docs/README
index 8556dd2..174f55a 100644
--- a/docs/README
+++ b/docs/README
@@ -1,22 +1,36 @@
-This directory contains the Sphinx documentation for libmaple.  You
-can generate HTML documentation using the Makefile if you have make,
-or using make.bat from Windows.
+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.
 
-For the impatient, you can build the HTML docs with (on Unix):
+You need a recent-ish version of doxygen in your PATH:
+
+    http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
+
+For the Doxygen-to-Sphinx bridge, we rely on a project called Breathe,
+by Michael Jones.  You must clone the breathe repository and set an
+environment variable BREATHE_HOME to be able to build the
+documentation.  Something like this on bash:
+
+    $ git clone http://github.com/michaeljones/breathe.git
+    $ export BREATHE_HOME /path/to/breathe/repo/
+
+You can now build the HTML docs with (on Unix):
 
     $ sudo easy_install -U Sphinx
     $ make html
 
-Which will produce HTML documentation in build/html.
+Which will produce Doxygen documentation in doxygen/xml, and HTML
+documentation (this is what you want to look at) in build/html.
 
 All of the documentation itself lives in source/.  The directory
 source/_static is for static content like style sheets;
-source/_templates contains Sphinx templates.
+source/_templates contains Sphinx templates (or, it would if we had
+any).
 
-The documentation is written in reStructuredText (reST); it's a Python
-thing that they use to produce the docs at python.org (which are
-beautiful, if you've never seen them).  You can read more about Sphinx
-here:
+The docs are written in reStructuredText (reST); it's a Python thing
+that they use to produce the docs at python.org (which are beautiful,
+if you've never seen them).  You can read more about Sphinx here:
 
     http://sphinx.pocoo.org/tutorial.html
 
@@ -24,5 +38,8 @@ Specific information on documenting C and C++ is available here:
 
     http://sphinx.pocoo.org/domains.html
 
-The file source/conf.py is an autogenerated configuration file; you
-can read it yourself.
+You can view the reST source for any generated page of documentation
+by clicking the "Show Source" link in the sidebar.
+
+The file source/conf.py is the Sphinx configuration file; you can go
+read it for more information about our setup.