Categories

BusPirate.com: Automated documentation updates

Posted on Tuesday, September 18th, 2018 in Bus Pirate, documentation by Ian

wx_camera_1523965080542

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.

buspiratecom-refmanual-600

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

buspiratecom-refmanualpdficon

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.

Automated updates

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

buspiratecom-testeditor

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.

Results files

buspiratecom-pipepy

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.

Templates

buspiratecom-template-entry

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

Command Reference, Self-test guide, Pull-up resistors guide, and Number entry guide are up now on the new site. More will come soon.

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.

test-rig

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.

 

 

This entry was posted on Tuesday, September 18th, 2018 at 3:37 pm and is filed under Bus Pirate, documentation. You can follow any responses to this entry through the RSS 2.0 feed. You can skip to the end and leave a response. Pinging is currently not allowed.

One Response to “BusPirate.com: Automated documentation updates”

  1. Pixelbrick says:

    I am liking where this is going very much. Cheers Ian.

Leave a Reply

Notify me of followup comments via e-mail. You can also subscribe without commenting.

Recent Comments

  • Sjaak: I love those spade connectors. Where to get them?
  • Justin Myers: Always worth a shot!
  • Jack: Honesty is based upon objective fact, and truth upon perception which is invariably subjective. Therefore be honest, and let history make its own decisions.
  • Crawford: Lucky?
  • hli: Sunday++