OSSBarCamp Talk on Automated Documentation
You can download PDFs of the handout from my talk at the September 2009 OSSBarCamp in the sidebar. Unfortunately the hyperlinks aren’t live in the PDFs, so here are the software projects I mentioned in my talk. The outline was done using FreeMind which I’ve just started playing around with.
Webby is primarily a tool for building static websites, but its combination of Rake and a generic filter/helper structure makes it phenominally powerful for managing any kind of collection of documents. I use Webby as the glue for my Automated Documentation “stack”.
Gorgyrella is my Ruby port of the Python library Idiopidae. Gorgyrella lets you add special comments to your source code to define sections, which you can then pull out to include in documenation or to execute with Dobby.
Dobby is still in its infancy, but its goal is to allow you to run snippets of code in an interpreter and display the output in a document. What makes it especially convenient for writing tutorials is that you can keep a Dobby session open, run a setup script invisibly, and only show the output of running a few lines of script at a time but with the memory of any previous commands still intact. Dobby currently supports R and Python, but in principle can be adapted to support any software with a command line interface.
The projects which use Webby+Gorgyrella for their documentation are:
Write native Excel files using just pure Ruby. This one has the screenshot automation.
Interface between R + Bloomberg financial data.
I currently use Bazaar for version control. It’s a distributed version control system and very easy to install and get started with. Once you have it installed if you want to check out the source code for Surpass to see how the documentation is compiled, then you just need to type:
bzr branch http://ananelson.com/code/surpass
and this will give you a bzr repo named “surpass” in whatever directory you typed the command. I’ll try to set something up with zipped copies of the latest version for those who don’t want to install Bazaar. Hey! I can automate that with Webby! ;-)