diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 350 |
1 files changed, 15 insertions, 335 deletions
@@ -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 |