Literate Programming with Marginalia

Here is the source code of the project I'm working on at home, formatted by Marginalia: http://neillalexander.github.com/rtm-clj/uberdoc.html.

I love it. Having something so beautifully formatted really motivates me to write comprehensive documentation. I'll be using it in all my Clojure projects from now on.

The set up was fairly straightforward, so I won't go through it in depth here. Once I had it working, I wanted to find an easy way to publish the updated documentation, and make it easily readable on-line. The solution was GitHub pages, and git submodules.

Here's what I did:

• Set up a project page for the project using instructions at http://pages.github.com/.

• Added that branch as a submodule of the main source code in the docs directory.

git submodule add git@github.com:NeillAlexander/rtm-clj.git docs
cd docs
git checkout gh-pages

• Created index.html which redirects to uberdoc.html
• Back up to the parent directory and run 'lein marg'

Running 'lein marg' creates a new version of uberdoc.html in the docs directory, which is actually the gh-pages branch of the overall project. Pushing the change therefore makes it available at http://neillalexander.github.com/rtm-clj/uberdoc.html