Nat Pryce released Code Guide, a tool to create interactive code documentation. See his blog post announcement. It’s written in Python and works for Python and Java code. But since Python and Ruby comments look the same, parsing Ruby code works, too.

Check out one of the examples to see what the output looks like. There are other examples on Nat’s blog.

I really like these already but wonder how long tutorials would work, where paragraphs of text, section headings and code snippets flow in a single document.

Code Guide uses Markdown to markup the documentation. You also have to mark comments as Code Guide-style with a pipe:

# Python example. (This line will not be processed by Code Guide)
#| This is the start
some_code()
#|.

I’ll have to play with this for some time longer to see whether code becomes unbearable cluttered with exhaustive documentation texts.

That the documentation is included in the code also is the nice thing about this project: Nat found it is infeasible to write documentation and tutorials containing code examples in a place outside of the code itself. You’d have to maintain both the code base and the example code listings, keeping them in sync. Code Guide does solve this issue.