Split up README into separate files.

The README is pretty long (over 1500 words). Nobody's going to read
that. Make it short, and put the long-winded bullshit into other files
that are clearly labeled as being for docs maintainers.

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

1 files changed, 15 insertions, 335 deletions

diff --git a/README b/README
index c11fc72..60fb888 100644
--- a/README
+++ b/README
@@ -1,344 +1,24 @@
-Introduction
-------------
-
-This repository contains reStructuredText (reST) source files used to
-generate the documentation for LeafLabs' libmaple and Maple IDE
-projects.  For more information on these projects, see their GitHub
-pages:
-
-    https://github.com/leaflabs/libmaple
-    https://github.com/leaflabs/maple-ide
-
-While the two projects are developed separately, they are released in
-lockstep, and Maple IDE depends upon libmaple.  (libmaple doesn't
-depend on Maple IDE).
-
-The generated documentation for the latest libmaple and Maple IDE
-release is available online in HTML form:
+This repository contains source files used to generate the
+documentation for LeafLabs' libmaple and Maple IDE projects [*]. The
+HTML documentation generated from these sources is available online:
 
     http://leaflabs.com/docs/
 
-The web interface is the recommended way for users to read the
-documentation.  Older versions are available as well:
-
-    http://static.leaflabs.com/pub/leaflabs/maple-docs/
-
-This file contains instructions for generating the HTML files.  It
-also contains guidelines for the documentation's maintainers.
-
-About the Documentation
------------------------
-
-The docs are written in Sphinx's extensions to reStructuredText
-(reST).  You can read more about Sphinx here:
-
-    http://sphinx.pocoo.org/tutorial.html
-
-Much of the documentation is pulled out of the libmaple source code.
-libmaple documents itself using Doxygen:
-
-    http://doxygen.org
-
-We use a Sphinx plugin called Breathe to parse Doxygen's XML output
-into a form usable by Sphinx.  You can read more about Breathe here:
-
-    http://michaeljones.github.com/breathe/
-
-Documentation Build Steps
--------------------------
-
-First, you will need to install some dependencies (Doxygen, Sphinx,
-and Breathe).
-
-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
-
-   You need Sphinx version >= 1.0.6.
-
-You are now ready to build the documentation.  First, you'll produce
-Doxygen XML output, then you can generate the HTML documentation.
-
-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
-   rebuild libmaple's Doxygen XML output.  That is, from within the
-   libmaple repository (i.e., NOT THIS REPOSITORY), run:
-
-    $ make doxygen
-
-2. Finally, you can build the documentation (in this folder):
-
-    $ make html
-
-   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
----------------------------------------
-
-Just 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).
-
-Read more about Sphinx and use the existing docs source as an example
-when writing yours.  The directory tmpl/ contains template ReST files
-you should sometimes use when creating a new 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.
-
-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
-  * 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.
-
-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).
+The above URL is the recommended way for users to read the
+documentation.  The docs for the latest release are always available
+there.
 
-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.
+Older versions are here:
 
-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 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
+    http://static.leaflabs.com/pub/leaflabs/maple-docs/
 
-  Where C' performs the same changes as C.
+The file README-building.txt explains how to build the HTML docs.
 
-- Push your fixes to GitHub.
+The file README-maintainers.txt contains important information for
+maintainers of the documentation (e.g. how to add docs for a new
+board, how to cut a release version of the docs, etc.).
 
-- Distribute the updated docs.  These are world-visible here:
+[*] libmaple and Maple IDE themselves are in separate repositories:
 
-      http://static.leaflabs.com/pub/leaflabs/maple-docs/
+    https://github.com/leaflabs/libmaple
+    https://github.com/leaflabs/maple-ide