It’s amazing what you find if you just bother to look.

I was updating Zoodango’s internal rdocs, and I got thinking, the layout that rdoc generates by default is not how I’d do it. I often have fairly long lists of files, classes, modules, and methods, and the three scrolling lists across the top are too small to scroll effectively. Just try scrolling through the class list on the Ruby core library rdocs and you’ll see what I mean.

Most people’s screens and browser windows are horizontal, so I couldn’t understand why the template would take up valuable vertical real estate in that way. The rdocs for Rails look much better—moving the scrolling lists to the left side. Not to mention that the formatting looks quite a bit nicer.

Lo and behold, I just discovered, it’s not hard to get the Rails-style view in your rdocs. The Rails rdoc template, it turns out, was written by Jamis Buck, the author of Capistrano, way back in early 2005. The template itself, along with instructions on how to use it, are on this blog posting from back then.

Jamis’s instructions say to install the jamis.rb file in your ruby installation. If you’re like me and don’t like mucking with your ruby installation, you can install it anywhere covered by your ruby require path, such as your $RAILS_ROOT/lib directory. It just needs to be in the path that rdoc expects; e.g. $RAILS_ROOT/lib/rdoc/generators/template/html/jamis.rb.