aboutsummaryrefslogtreecommitdiffstats
path: root/docs/README
diff options
context:
space:
mode:
Diffstat (limited to 'docs/README')
-rw-r--r--docs/README83
1 files changed, 59 insertions, 24 deletions
diff --git a/docs/README b/docs/README
index b467d2d..326d278 100644
--- a/docs/README
+++ b/docs/README
@@ -3,46 +3,81 @@ 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.
-You need a recent-ish version of doxygen in your PATH:
+Documentation Build Steps
+-------------------------
- http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
+1. You need a recent-ish version of Doxygen in your PATH:
-For the Doxygen-to-Sphinx bridge, we rely on a project called Breathe,
-by Michael Jones.
+ http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
-***** You must clone the LEAFLABS VERSION OF THE breathe repository ******
+2. Install breathe, which does Doxygen-to-Sphinx conversion:
- ... and then set an environment variable BREATHE_HOME to be able to
-build the documentation. Something like this on bash:
+ 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 can now build the HTML docs with (on Unix):
+ (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
-Which will produce Doxygen documentation in doxygen/xml, and HTML
-documentation (this is what you want to look at) in build/html.
+ (Read the Makefile for more targets).
-All of the documentation itself lives in source/. The directory
-source/_static is for static content like style sheets;
-source/_templates contains Sphinx templates (or, it would if we had
-any).
+Reading and Modifying the Documentation
+---------------------------------------
-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:
+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.
- http://sphinx.pocoo.org/tutorial.html
+Just point your web browser at the file
+
+ libmaple/docs/build/html/index.html
-Specific information on documenting C and C++ is available here:
+it corresponds to the Sphinx file
- http://sphinx.pocoo.org/domains.html
+ 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 reST source for any generated page of documentation
-by clicking the "Show Source" link in the sidebar.
+You can view the 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.
+The file libmaple/docs/source/conf.py is the Sphinx configuration
+file; you can go read it for more information about our setup.