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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
This file contains information useful for the documentation's
maintainers. Users can read the HTML for the latest release here:
http://docs.rambutan.cc/projects/librambutan/en/master/
This file is out of date (libmaple era). librambutan uses readthedocs.org to
auto-build documentation.
Building Documentation for a Release
------------------------------------
This is the procedure to follow when building the documentation for a
versioned release.
Read the following "Background" section if you've never done this
before (or haven't done it in a while; things change). Then do the
steps in the "Preparation" and "Cutting the Release" sections that
follow it.
If you're bugfixing the docs for a release that's already been
shipped, skip to "Maintaining a Release", below.
~~~~~~~~~~
Background
~~~~~~~~~~
As a lightweight form of issue tracking, the documentation sources are
sprinkled (not to say "littered") with comments that begin with FIXME
or TODO, optionally followed by [milestone].
Here's a hypothetical example:
.. TODO [1.4.0] Replace this section; new API is incompatible with 1.3.7
This means you should replace the docs section following the comment
before you build the HTML for version 1.4.0.
Here's a command line you can use to list the TODOs in the
documentation sources (run it from the top-level directory in the
repository):
$ git grep -n 'FIXME\|TODO'
You can use the following to temporarily alias the above mouthful to
'todos':
$ alias todos="git grep -n 'FIXME\|TODO'"
Then you can just run
$ todos
to measure the joy that awaits you.
~~~~~~~~~~~
Preparation
~~~~~~~~~~~
- FINISH THE FIXMEs/TODOs FOR THE CURRENT RELEASE!
You may violate assumptions made elsewhere in the documentation if
you don't. This can lead to incoherent or incorrect documentation,
which is usually worse than none at all.
If the release you're building is vA.B.C, you can see the relevant
TODOs with:
$ todos | grep A\.B\.C
If you find that you really can't finish the TODO, you should bump
the version number in the comment. Don't do this out of laziness.
Seriously, don't. We may have made promises to the users about what
would happen when, and you might be breaking them.
- Pick the low-hanging fruit on any other FIXMEs/TODOs.
- Ask Git to tell you what's happened since the most recent libmaple
release, and make sure that any major, potentially
backwards-incompatible, etc. changes are appropriately documented.
You can use three dots ("...") between the git tags for those
releases in concert with "git log --oneline" to do this.
For instance, from the libmaple repository, you can use the
following to tell you what happened in between 0.0.9 and 0.0.10:
$ git log --oneline 0.0.9...0.0.10
As an example of what the output might cause you to do, consider the
following line (which appears in the output for 0.0.9...0.0.10):
4941335 Adding rcc_dev_clk(), an accessor for a peripheral's clock line.
Did the author of that commit (or some other interested party)
remember to pull in the documentation for rcc_dev_clk() into the
libmaple API page for rcc.h? Go check!
- Do something similar for Maple IDE. The IDE changes a lot more
slowly, so there should be less to do.
~~~~~~~~~~~~~~~~~~~
Cutting the Release
~~~~~~~~~~~~~~~~~~~
- Make a release branch in Git. For release A.B.C, call it
vA.B.C-maintenance. You spell that
$ git checkout -b vA.B.C-maintenance
DON'T MAKE A TAG. There are inevitably mistakes in the docs, some
of which will be noticed and corrected, making a fixed tag useless.
When you correct the errors, you'll need to update this branch,
possibly also cherry-picking or otherwise adding into master. See
"Maintaining the Release", below.
- Do all the TODOs which must happen for _every_ release. (These are
distinct from the ones that must happen for some _particular_
release). You can find most of these with
$ todos | grep RELEASE
However, you'll also need to check source/conf.py, as e.g. a
release's configuration file needs to have a version entered into
it.
DON'T FORGET TO COMMIT YOUR CHANGES.
- Run "$ make mrproper" from the libmaple directory, and "$ make
clean" from this directory, in order to wipe out existing old docs.
- Run "$ make doxygen" from the libmaple directory, and copy its
doxygen/xml directory to doxygen/xml in this directory, and commit
it in the vA.B.C-maintenance branch.
(This makes later maintenance commits easier, and keeps a single
- Finally, you can actually build the docs. (See README-building.txt
for instructions if you've never done this before.)
DON'T FORGET TO PUSH THE RELEASE BRANCH TO GITHUB.
Maintaining a Release
---------------------
So a released version's documentation contains unforgivable lies, huh?
It needs to be updated RIGHT AWAY, you say? Here's what you do:
- Check out the release branch for the version of the docs you care
about (see "Cutting the Release", above).
- Make your changes.
- Rebuild the docs (see the last two steps in "Cutting the Release")
and look at the changed pages.
- If your changes also need to happen on the master branch, make them
appropriately.
Advice: git cherry-pick is your friend. Let's say you're on branch
"vX.Y.Z-maintenance", and you want to get commit C onto master:
o---C vX.Y.Z-maintenance
/
-o---o---o---o master
The recipe is:
$ git checkout master
$ git cherry-pick C
Which (if there are no conflicts) will result in:
o---C vX.Y.Z-maintenance
/
-o---o---o---o---C' master
Where C' performs the same changes as C.
- Push your fixes to GitHub.
- Distribute the updated docs. These are world-visible here:
http://docs.rambutan.cc/
Adding a New Board
------------------
Adding documentation for a new board is not just a matter of shoving a
file for it into source/hardware/!
Other things you must consider:
- Various places in the docs link to particular kinds of pin maps for
each board. When you add a new board, you must update these as
well. Here's the list; please keep it current (files are relative
to the source/ directory):
* external-interrupts.rst: EXTI line pin maps
* timers.rst: timer pin maps
* adc.rst: low-noise ADC banks
* usart.rst: USART pin maps
* gpio.rst: master pin maps
* bootloader.rst: flashing a custom bootloader
- The quickstart document may not explain how to use the new board.
If the board is different enough, a new, special-purpose quickstart
may need to be written for it. Therefore, read the quickstart in
its entirety and update it appropriately.
Take this step seriously. The quickstart is the first thing users
read when starting out, and first impressions matter.
|
