Update README.

Add information on how the documentation is maintained, with specific
notes on the important use cases (adding a new board, versioned docs
build and their maintenance).

1 files changed, 196 insertions, 1 deletions

diff --git a/README b/README
index 15c1006..d757853 100644
--- a/README
+++ b/README
@@ -23,7 +23,8 @@ documentation.  Older versions are available as well:
 
     http://static.leaflabs.com/pub/leaflabs/maple-docs/
 
-This file contains instructions for generating the HTML files.
+This file contains instructions for generating the HTML files.  It
+also contains guidelines for the documentation's maintainers.
 
 About the Documentation
 -----------------------
@@ -98,6 +99,10 @@ Doxygen XML output, then you can generate the HTML documentation.
 
    On Windows, use the batch file make.bat instead.
 
+  As of 8 September 2011, building the docs generates a bunch of
+  errors/warnings.  Most of these are spurious and appear to be
+  Breathe's fault.  C'est la vie.
+
 Reading and Modifying the Documentation
 ---------------------------------------
 
@@ -121,3 +126,193 @@ All of the documentation which isn't pulled out of source code
 comments lives in source/.  The directory source/_static/ is for
 static content (like style sheets); source/_templates/ is meant to
 contain Sphinx templates.
+
+The remaining sections describe what to do under various circumstances
+when modifying or building the docs.
+
+Adding a New Board
+------------------
+
+Adding documentation for a new board is not just a matter of shoving a
+file for it into source/hardware/!
+
+- 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
+
+- 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.
+
+Building Documentation for a Release
+------------------------------------
+
+This is the procedure to follow when building the documentation for a
+versioned release (as such, it's mostly intended for LeafLabs people).
+
+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 on OS X and Linux to list the TODOs
+in the documentation sources (run it from the same directory as this
+README):
+
+    $ find . -name '*.rst' | xargs egrep --color=auto -n '(FIXME|TODO)'
+
+You can use the following to temporarily alias the above mouthful to
+'todos':
+
+    $ alias todos="find . -name '*.rst' | xargs egrep --color=auto -n '(FIXME|TODO)'"
+
+Then you can just run
+
+    $ todos
+
+to measure the joy that awaits you.
+
+Windows users: I'm not sure what the equivalent of grep is on your
+system.  If you're using Git, I presume you've got a Bash shell
+available to you due to msysgit; try running the above commands there.
+
+BE ADVISED: that only finds the comments embedded within .rst files.
+You also need to check for these in source/conf.py; there may be
+others.  If you have ack (which might be called "ack-grep" on your
+system) installed, you can instead use
+
+    $ ack --type-set rst=.rst --type-set txt=.txt --ignore-dir=build '(FIXME|TODO)'
+
+to get the same output, but for all the file types we care about.
+
+    ~~~~~~~~~~~
+    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 old docs.
+
+- Finally, you can actually build the docs.  "$ make doxygen" from
+  libmaple followed by "$ make html" from here.  The sources you want
+  will be in build/html.  Wooo!  You're done!  Distribute the results
+  appropriately (e.g. by bundling them with the IDE release).
+
+  Don't forget to push the release branch to the leaflabs-docs repo on
+  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 step in "Cutting the Release").
+
+- If your changes need to happen on the master branch, make them
+  appropriately.
+
+- Push your fixes to GitHub.
+
+- Distribute the updated docs.