aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@mit.edu>2010-10-11 20:02:04 -0400
committerMarti Bolivar <mbolivar@mit.edu>2010-10-11 20:02:04 -0400
commit56078b6b44f3a3e724f3ec2e3173075ab9043310 (patch)
treed834cfbb1196d26bc8866196b16fd8f8579b9456 /README
parent8de4fe4b0f3e28c99cac6dbf919dfa9b0009765f (diff)
downloadlibrambutan-56078b6b44f3a3e724f3ec2e3173075ab9043310.tar.gz
librambutan-56078b6b44f3a3e724f3ec2e3173075ab9043310.zip
more docs
Diffstat (limited to 'README')
-rw-r--r--README41
1 files changed, 29 insertions, 12 deletions
diff --git a/README b/README
index 8556dd2..174f55a 100644
--- a/README
+++ b/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.