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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
This file explains how to build the HTML documentation. Users can quickly read
the HTML for the latest release here:
http://docs.rambutan.cc/projects/librambutan/en/master/
Install Dependencies
--------------------
First, you will need to install some dependencies (Doxygen, Sphinx,
and Breathe).
1. Much of the documentation is pulled out of the libmaple source
code's Doxygen comments, so you need Doxygen in your PATH:
http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
2. Documentation not taken from the libmaple sources is written in
Sphinx's extensions to the reStructuredText (reST) markup language.
(More about Sphinx: http://sphinx.pocoo.org/tutorial.html).
These are your choices for how to install Sphinx:
- From a Linux package manager, eg:
$ sudo apt-get install python-sphinx
- From an OS X package manager, like MacPorts or homebrew.
- Via pip:
$ sudo pip install Sphinx
- Via easy_install:
$ sudo easy_install -U Sphinx
- From source or .egg:
http://pypi.python.org/pypi/Sphinx#downloads
You need Sphinx version >= 1.0.6.
3. We use a Sphinx plugin called Breathe to parse Doxygen's XML output
into a form usable by Sphinx. (More about Breathe:
http://michaeljones.github.com/breathe/).
The more recent versions of Breathe seem to have all the features necessary
to build these docs, so you can install the distribution version (breathe-doc).
Alternatively, LeafLabs sometimes patches Breathe for the purposes of building
docs, so clone the LeafLabs Breathe tree from GitHub (somewhere
else on your system, NOT in the librambutan repo):
- LeafLabs developers, clone with push permissions:
$ git clone git@github.com:leaflabs/breathe.git
- Everyone else, clone without them:
$ git clone git://github.com/leaflabs/breathe.git
After that's done, set environment variable BREATHE_HOME to point to
Breathe. Something like this in Bash:
$ export BREATHE_HOME=/path/to/breathe/repo/
(You'll want this in your shell startup script.)
Build the Docs
--------------
You are finally ready to build the documentation. First, you'll
produce Doxygen XML output, then you can generate the final HTML docs.
1. Before the first time you run Sphinx (and any time the Doxygen
comments in the libmaple source code are changed), you'll need to
re-run doxygen on the top level of librambutan.
$ cd /path/to/top/level/librambutan
$ make doxygen
Doxygen will yell at you a lot; it's generally safe to ignore it.
2. Finally, you can build the HTML:
$ cd /path/to/docs
$ make html
On Windows, you can supposedly use the batch file make.bat instead.
Breathe will yell at you a lot; it's often safe to ignore this,
too. C'est la vie.
Read and Modify the Docs
------------------------
Point your web browser at the file
build/html/index.html
For the most part, the file build/html/foo.html is built from
source/foo.rst. (The index is an exception, because we needed to
hand-hack the HTML to get the "Contents at a Glance" section to look
nice).
All of the documentation which isn't pulled out of libmaple's Doxygen
comments lives in source/. The directory source/_static/ is for
static content (like style sheets); source/_templates/ is meant to
contain Sphinx templates.
Read more about Sphinx and use the existing source for
examples when writing new docs. The directory tmpl/ contains template
ReST files you should sometimes use when creating a page that follows
a pattern (like a libmaple API page), in order to keep the style
consistent.
The file source/conf.py is the Sphinx configuration file; you can go
read it for more information about our setup.
|
