Up-to-date documentation makes a project easy to learn about, but its a really boring job that takes a lot of time. Even great documentation eventually has outdated examples and screenshots that don’t quite match the latest version.
BusPirate.com has a hacked together toolchain to keep the documentation fresh.
It’s a three part process:
- Test scripts run demos on actual Bus Pirate hardware
- Results files are uploaded to BusPirate.com
- Tutorial templates and the results files are merged to make updated docs
Hardware and firmware specific docs
Bus Pirate documentation is full of version caveats like “Hardware v4+ only” and “Firmware v5.1+”. BusPirate.com docs are versioned, and just shows the stuff that matters for your version. Choose a hardware and firmware from the menu to see the docs for that specific combination.
Developers still need to add new feature information manually, but the huge task of “refreshing” everything after a firmware release can be automated. We took a three step approach: test scripts that run commands on actual Bus Pirate hardware, results files that capture the test output, and templates that merge with result files to create version-specific documentation.
Test scripts are just a list of commands to run on the Bus Pirate, for example running a self-test. A test has multiple steps, and each step has one or more Bus Pirate commands. We build the demos with a simple editor, then dump them to JSON in a file. Here’s the test script that runs all the commands shown in the reference manual.
pipe.py sends commands in the test script to a Bus Pirate. It also records the terminal output to a results file. Result files are uploaded to BusPirate.com. Here’s the results file from the reference manual test script.
Demos and docs are blade templates. A template merges with a results file to show the tutorial exactly as it appears on a hardware and firmware combination. It’s not super elegant, the version specific stuff is done with a bunch of PHP if statements.
Taking it further
Ideally the update process will be triggered by an automated firmware release. An RPi in the workshop will bootload the new firmware into the Bus Pirate, run the test scripts, and upload the results without any intervention.
A test rig with a bunch of devices might be a cool way to do release testing. Scripts could test various firmware features on real devices. Comparing the scripted test results with a previous release would highlight things that may be broken. Our goal is to hack together something that does comprehensive release testing with no manual effort.
Thursday we’ll document the automated build server that’s kicking out freshies every time there’s new code in the git repo.