generating prettier rdoc

If you've ever looked at the rails documentation you may have wondered how DHH and crew generated it. I find it a lot prettier to look at than vanilla rdoc. It turns out that you can quite easily change the template used by rdoc.

To get the rails api look, just download the jamis rdoc template, courtesy of Jamis Buck. Copy it into your rdoc html templates directory, which on my Ubuntu system sits at /usr/lib/ruby/1.8/rdoc/generators/template/html/. Then pass '--template=jamis' to rdoc and you're good to go.

Another template of note is allison, which comes packaged as a gem, and is not installed directly with the other templates. It is a bit annoying when you are writing a rake file because you must spell out the entire path to the template to get it to load.

Note that if you use rake's rdoc task you must use the template method of the task object to set it, you cannot add '--template' to the rdoc options it won't work for some reason. I wasted a good 15 minutes figuring that one out.

Below are all the templates i know of. Those marked with * are not included by default. If you know of any other nice templates out there, please let me know and I'll add them to the list.

html

the default template we know and, well, just live with.

hefss

similar in layout to the jamis template but using a rather unwieldy fourth frame for the main content, and (imho) nowhere near as pretty

kilmer

this one is layed out just like jamis, but is a bit lighter weight

old_html

just like regular html but with a lighter color scheme. i almost like it better than the standard html template

jamis*

a nice template used by rails, rake, and a host of other projects online

allison*

another nice one which, refreshingly, has no frames

one_page_html

this one doesn't even work for me, i get

  Generating HTML...
  rake aborted!
  uninitialized constant RDoc::Page::STYLE

As you can see there are quite a few templates to choose from. It would be nice if there were some standardized way of packaging and distributing them though, maybe even with a web based repository that users could submit to. I'd also like to be able to include the template which i want used when the rdoc for a gem is automatically generated, something which i don't think is possible at the moment? Maybe some of you out there know how to do this. Hope I've been of some help, cheers and happy hacking.