Literate programming using Documenter.jl and Entangled

Here I explain my workflow for literate programming in Julia using Documenter.jl and Entangled

Literate Programming

Literate programming is a method of programming where you write all your code in a markup document (traditionally LaTeX, but these days Markdown is the obvious choice) in the form of code blocks. The technique has been popularised in a weaker form by the use of notebooks. There are some fundamental problems with the way notebooks are used. Joel Grus explains this very eloquently: I don't like notebooks.

Real literate programming works with a system of references. This form of literate programming is completely generic over languages, and much more powerful than what you can do with Literate.jl for instance. You give every code block a name. In Markdown this can be done by annotating code blocks with identifiers:

``` {.julia #pythagoras}
sqrt(x^2 + y^2)
```

We can reference this code block in other blocks as follows:

``` {.julia #hypothenuse}
hypothenuse(x, y) =
     <<pythagoras>>
```

We can build a complete program by annotating file output:

``` {.julia file=src/Geometry.jl}
module Geometry
<<hypothenuse>>
end  # module
```

This system of references was pioneered by Donald Knuth, and simplified by Norman Ramsey in Noweb.

I have developed a tool called Entangled that helps with writing literate programs. It is a daemon that watches your Markdown files for changes and keeps the tangled source code up-to-date. Even better, if you then change any of the tangled source files, these changes are automatically merged back into your markdown.

Usually I combine Entangled with Pandoc, but when the main language is Julia, Entangled also works together really well with Documenter.jl.

Howto combine with Documenter.jl

Traditional documentation in Julia is usualy made using the Documenter module. This has features for doc-testing and also inline code evaluation that combine well with Entangled. All it needs is a little bit extra scripting to annotate the code blocks in the generated output.

I use an Awk script to filter the Markdown source files, so that annotations are added where needed. To run this pass before the rest of Documenter.jl I have customized make.jl.

Since we are celebrating the happy Yule tide of Advent of Code, I have my Julia solutions in literate form. Enjoy!