I'd love to know if there's a lib for generating annotations like this from source comments. I've always loved docs tha include the code for reference, helps to see what's actually going on :)
http://github.com/fitzgen/pycco
And a first cousin, once removed: Dox (JavaScript):
Pycco claims to support Python, Ruby, JavaScript, CoffeeScript, Scheme, and Lua.
-----