path: root/README

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:

    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 modify 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).

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 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/