merge libmaple docs ("leaflabs-docs") into ./docs

In the past, libample documentation was forked out of this repository
because the documentation had increased in scope. For the librambutan,
and the rambutan project in general, we will try to keep documentation
closer to the source code, so the librambutan-specific documentation
should live here. Other sections of leaflabs-docs will be culled in a
following commit.

This merge attempts to maintain history by using a subtree strategy.
Followed directions at:

    http://nuclearsquid.com/writings/subtree-merging-and-you/

Full history for files should be accessible using the "--follow" flag to
git log, eg:

    git log --follow docs/source/adc.rst

It should be possible to pull patches from leaflabs-docs with:

    git pull -s subtree leaflabs-docs master

... at least until the docs in this repository diverge significantly.

1 files changed, 215 insertions, 0 deletions

diff --git a/docs/README-maintainers.txt b/docs/README-maintainers.txt
new file mode 100644
index 0000000..48e8e5c
--- /dev/null
+++ b/docs/README-maintainers.txt
@@ -0,0 +1,215 @@
+This file contains information useful for the documentation's
+maintainers. As such, it's probably only useful to LeafLabs
+developers. Users can read the HTML for the latest release here:
+
+    http://leaflabs.com/docs/
+
+Things you can learn how to do from this file:
+
+- Cut a release version
+- Fix errors in/otherwise maintain the current docs release
+- Add docs for a new board
+
+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://static.leaflabs.com/pub/leaflabs/maple-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/!
+
+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.