This document is a literate program¶
Intro¶
Literate programming invented by Don Knuth is about generating working code and documentation from a single source, where things are written in a psychological order.
Screencast¶
Project Genesis¶
While working on my app Plannr, I found the codebase difficult to explore and adding features annoying; unlike the initial phases of the project. A typical codebase will have tests, frontend and backend located in different files. Navigating them is a pain and has a lot of context switching involved. I started using a vim hyperlink plugin to link different sections of code together. Although initially useful the links themselves were getting out of hand and then I remembered that Literate Programming had cross-referencing links too.
It was after seeing the video below I decided to give literate programming a serious shot,
After messing with lit, pandoc, noweb and litpro I now use cog, jinja2, markdown, sphinx and python triple quotes to write literate code. Much as I suspected the context switching between files is completely gone and literate programming has had a profound effect on the codebase.
The main reason for using this solution is for allowing the ability to hide sections in docs. yarner, lit and litpro are better options if you don’t want that. The initial work was done in litpro. With this tool both code and documentation can have arbitrary order. As this uses jinja2 it can appeal to web developers who are already used to writing templated code. Reading the code in the browser was worth all the boilerplate. Its not a pretty solution but its not limited by assumptions of other tools.
Example¶
Checkout this amazing book on physical rendering that won the 2014 Academy Award for Technical Achievement, written using another literate tool noweb.
Simply put wheel transforms the following source code,
into docs with source code.
Checkout the apps Bitrhythm and Plannr to get an idea of the end result. You can see that the tests, templates, event handlers and backend next to each other.
The next sections will explore my notes on literate programming. If you want to jump straight to a working example go to Code Walkthrough with Example.