Site: Jekyll
How do you add documentation to your project? My favorite is to crank out Pages and start writing, but unfortunately not everyone working on the project has Pages, and Pages doesn’t generate the best HTML.
Wikis are much better for sharing, but all the Wikis I worked with had two fundamental problems. One, they don’t work offline very well, I, on the other hand, work offline very well. It’s amazing what an online break can do for your productivity. Two, Wikis maintain their own version of history, different from the history of the code it documents.
Let’s say I’m working on a new feature, and I’m doing that under the branch BUILDR-136. If I edit the Wiki and document the new feature, everyone gets to read documentation for a feature that’s not yet available. If I don’t edit the Wiki now, will I remember to edit it just before cutting a release? Life is easier when you start including the documentation as part of the source code. When you merge a branch, you also merge all the documentation of that change/feature.
To make that possible you need a human-editable format. Source control systems don’t handle .doc and ODF flies very well. We’re using Textile for the content and HTML for the layout. Not exactly at the same league, but they’re both very popular and tolerant markups, so easy to live with.
Previously we used our home-grown tool called Docter. It works really well, but my philosophy is that it’s better to have less code to maintain, so I switched to using Jekyll instead. As an added bonus, we also use Jekyll for all our Github pages.
The switch wasn’t particularly eventful, although I did run into a couple of gotchas. Jekyll uses Pygments for syntax highlighting, and in 0.4.1 has a bug that leaks processes. Until 0.4.2 comes out, we’re just monkeypatching Jekyll using Ryan Tomayko’s fix.
The second issue: I like having a table of contents on each page, especially since some pages can run long. I don’t like writing that ToC into every page, which was easily fixed by adding a Liquid ToC filter.
I think the results speak for themselves.
PDF: PrinceXML
The site has one page per section. Some people prefer the documentation to come in a single file, easier for reading offline, in one go, or printing out. You can also get the documentation as a PDF file. Here are the three steps it took to create high qualify PDF.
In the first step, add a CSS file specifically for printing. The one we use controls the print margin, adds a header with the page number and title, alternating on odd/even pages, and hide various elements that are unnecessary in print (sidebar, footer, etc).
In the second step, add a preface page with the document title, H1 table of contents, copyright notice, etc.
In the third step, take all pages listed in the H1 ToC, add the preface, and run them all through PrinceXML. PrinceXML converts HTML/CSS into PDF with outstanding results, and will also handle the hyperlinks for you and generate table of contents for navigation.
RDoc + Hanna
My favorite RDoc template is Hanna. It’s a simple gray/white/blue theme, won’t impress your designer friends, but very readable, and that’s what counts. The navigation is on the left, which works better for widescreen displays, and includes a very handy search bar that does as-you-type method search (e.g. hit ‘def’ to find ‘before_define’).
Before Hanna we used Allison, pretty template but search and navigation wasn’t as good. There’s also Darkfish, the default template that comes with RDoc 2.3/2.4, but it’s not as easy to navigate and lacks method search.
Update: Two weeks later we’re switching over to SDoc. SDoc comes with just as simple/readable template, much smarter and downright awesome search bar, and can even link each method back to the source code on Github. Judge for yourself.
Speaking of which, are you still using the default RDoc that ships with Ruby? Version 1.0.something, dated Nov 2004? Time to upgrade. RDoc 2.3/2.4 are way faster and don’t take over your computer every time you install a gem.
These instructions are for RDoc 2.3, since mislav-hanna doesn’t work with 2.4 yet, but they will install both and then use the Hanna template to document all your installed gems:
gem install rdoc -v 2.3 gem source add http://gems.github.com gem install mislav-hanna hanna --gems
You can also configure Rubygems to use the template by adding rdoc: --template=hanna to your ~/.gemrc file.
For instant access to the gem documentation, run gem server from the command line and open the browser to http://127.0.0.1:8808/.
The Real Adam – Making the pretty docs