diff options
| -rw-r--r-- | README | 350 | ||||
| -rw-r--r-- | README-building.txt | 103 | ||||
| -rw-r--r-- | README-maintainers.txt | 209 |
3 files changed, 327 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 diff --git a/README-building.txt b/README-building.txt new file mode 100644 index 0000000..9a1a1ac --- /dev/null +++ b/README-building.txt @@ -0,0 +1,103 @@ +This file explains how to build the HTML documentation. As such, it's +probably only useful to LeafLabs developers. Users can read the HTML +for the latest release here: + + http://leaflabs.com/docs/ + +Install Dependencies +-------------------- + +First, you will need to install some dependencies (Doxygen, Sphinx, +and Breathe). + +1. Much of the documentation is pulled out of the libmaple source + code's Doxygen comments, so you need a recent-ish version of + Doxygen in your PATH: + + http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc + +2. Documentation not taken from the libmaple sources is written in + Sphinx's extensions to the reStructuredText (reST) markup language. + (More about Sphinx: http://sphinx.pocoo.org/tutorial.html). + + These are your choices for how to 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. + +3. We use a Sphinx plugin called Breathe to parse Doxygen's XML output + into a form usable by Sphinx. (More about Breathe: + http://michaeljones.github.com/breathe/). + + LeafLabs sometimes patches Breathe for the purposes of building our + docs, so clone the LeafLabs Breathe tree from GitHub (somewhere + else on your system, NOT in the leaflabs-docs repo): + + - LeafLabs developers, clone with push permissions: + $ git clone git@github.com:leaflabs/breathe.git + + - Everyone else, clone without them: + $ git clone git://github.com/leaflabs/breathe.git + + After that's done, set an environment variable BREATHE_HOME to + point to your clone. Something like this in Bash: + + $ export BREATHE_HOME=/path/to/breathe/repo/ + + (You'll want to put this in your shell startup script.) + +Build the Docs +-------------- + +You are finally ready to build the documentation. First, you'll +produce Doxygen XML output, then you can generate the final HTML docs. + +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 + re-run doxygen on libmaple. + + $ cd /path/to/libmaple + $ make doxygen + + Doxygen will yell at you a lot; it's generally safe to ignore it. + +2. Finally, you can build the HTML (in the leaflabs-docs repository): + + $ cd /path/to/leaflabs-docs + $ make html + + On Windows, you can supposedly use the batch file make.bat instead. + + Breathe will yell at you a lot; it's often safe to ignore this, + too. C'est la vie. + +Read and Modify the Docs +------------------------ + +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). + +All of the documentation which isn't pulled out of libmaple's Doxygen +comments lives in source/. The directory source/_static/ is for +static content (like style sheets); source/_templates/ is meant to +contain Sphinx templates. + +Read more about Sphinx and use the existing leaflabs-docs source for +examples when writing new docs. The directory tmpl/ contains template +ReST files you should sometimes use when creating a page that follows +a pattern (like a libmaple API 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. diff --git a/README-maintainers.txt b/README-maintainers.txt new file mode 100644 index 0000000..90ebfb5 --- /dev/null +++ b/README-maintainers.txt @@ -0,0 +1,209 @@ +This file contains information useful for the documentation's +maintainers. As such, it's probably only useful to LeafLabs +developers. Users can read the HTML for the latest release here: + + http://leaflabs.com/docs/ + +Things you can learn how to do from this file: + +- Cut a release version +- Fix errors in/otherwise maintain the current docs release +- Add docs for a new board + +Building Documentation for a Release +------------------------------------ + +This is the procedure to follow when building the documentation for a +versioned release. + +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 to list the TODOs in the +documentation sources (run it from the top-level directory in the +repository): + + $ git grep -n 'FIXME\|TODO' + +You can use the following to temporarily alias the above mouthful to +'todos': + + $ alias todos="git grep -n 'FIXME\|TODO'" + +Then you can just run + + $ todos + +to measure the joy that awaits you. + + ~~~~~~~~~~~ + 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 existing old docs. + +- Finally, you can actually build the docs. (See README-building.txt + for instructions if you've never done this before.) + + DON'T FORGET TO PUSH THE RELEASE BRANCH TO 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/ + +Adding a New Board +------------------ + +Adding documentation for a new board is not just a matter of shoving a +file for it into source/hardware/! + +Other things you must consider: + +- 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. |