aboutsummaryrefslogtreecommitdiffstats
path: root/docs/README
diff options
context:
space:
mode:
Diffstat (limited to 'docs/README')
-rw-r--r--docs/README41
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.