README


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

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.

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 LEAFLABS VERSION OF THE breathe repository ******

 ... and then set an environment variable BREATHE_HOME to be able to
build the documentation.  Something like this on bash:

    $ git clone git@github.com:leaflabs/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 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 (or, it would if we had
any).

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

Specific information on documenting C and C++ is available here:

    http://sphinx.pocoo.org/domains.html

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.