diff options
| -rw-r--r-- | README | 197 |
1 files changed, 196 insertions, 1 deletions
@@ -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. |