I'm intrigued by the concept of literate programming and interested in exploring options for a Scala project I'm working on right now. It looks like this one was done using Docco [1]. Docco supports Scala, and it appears to be a pretty lightweight approach, largely using Markdown. I'm curious whether any literate programming veterans have tooling they prefer?

[1] http://ashkenas.com/docco/

It depends on what you are looking for. Docco and friends seem to only be capable of reversing the relationship between comments and code.

However, they don’t allow you to structure the program however you might like independently the need order and _nesting_ of code. In a lot of cases you can get around this through appropriate design patterns.

I’ve recently taken a quite deep dive into possible tools for literate programming. I work with signal processing so code documentation is extremely important but also frustratingly challenging.

There are a lot of “old” tools for literate programming (noweb, FunnelWeb), and they all lack in platform support, but are exceptionally stable and quite pleasant to work with. The more modern “true” literate programming tools are typically using a form of markdown (no links since my notes are not at hand). The last group are the “coffee script style” tools and they seem to be quite popular and active.

It seems to be a case of natural selection for tooling: true literate programming is serverely disadvantaged in terms of IDE/editor support and the programming philosophy is, unfortunate, too different from the norm. Docco styles seems highly pragmatic in contrast.

One option I haven’t tried yet is Emacs’ org-mode which includes true literate programming support. I haven’t found much with regards to real-world usage.

I like that it is markdown and that it has a many-to-many mapping of input to output files.