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 It corresponds to the Sphinx file source/index.rst 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 - 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"). - If your changes need to happen on the master branch, make them appropriately. - Push your fixes to GitHub. - Distribute the updated docs.