blob: 326d278a3cf8b97e634d8660e36c3c877ae6c4b7 (
plain)
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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
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.
Documentation Build Steps
-------------------------
1. You need a recent-ish version of Doxygen in your PATH:
http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
2. Install breathe, which does Doxygen-to-Sphinx conversion:
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'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
(Read the Makefile for more targets).
Reading and Modifying the Documentation
---------------------------------------
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.
Just point your web browser at the file
libmaple/docs/build/html/index.html
it corresponds to the Sphinx file
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 source for any generated page of documentation by
clicking the "Show Source" link in the sidebar.
The file libmaple/docs/source/conf.py is the Sphinx configuration
file; you can go read it for more information about our setup.
|
