Want to stay on top? Ruby Weekly is a once-weekly e-mail newsletter covering the latest Ruby and Rails news.
     Feed Icon

RDoc: Some Alternative Ways Of Looking At Documentation

By Matthew Lang / May 22, 2009

The great thing about the Ruby language is that there’s always multiple ways of doing things. The same goes for reading the documentation of your installed gems. Here’s a few ways of viewing the RDoc documentation of your gems other than running the gem server command.

Gembox

Gembox (source) is a Sinatra based web application by Aaron Quint for browsing your RDocs. Once installed, Gembox lets you quickly browse through your gems as well as their included files and gem specs.

Running Gembox at your command-line starts a Sinatra application that gives you some basic information about your gems, including the RDocs for each gem. Aaron is hoping to add some more advanced options in the future. If you'd like to navigate your gem documentation in a more friendly format and getting more information on your gems than the standard interface, give Gembox a try.

Sinatra Rubygems

Sinatra-Rubygems is a project by Jesse Newland. Similar to Gembox, this is also a Sinatra based web application. However where this differs to Gembox is that rather than being designed to run from the command-line, Sinatra-Rubygems can be run on a Passenger enabled server. By using the PassengerPane you can have your RDocs running locally on your own web server.

Although there's slightly more to getting Sinatra-Rubygems up and running (but not by much!), this is handy for having your RDocs running locally.

Bdoc

If any of these sound like too much work and you just want quick and easy RDocs then check out Rich Manalang’s project Bdoc. Once run from the command-line, Bdoc puts together a nice little IFRAMEd HTML page that lets you browse through your RDocs. You can quickly switch between different gems and there’s no need to run a server to display your RDocs.

Bdoc might not be as fancy as any of the Sinatra based applications, but it's a simple idea and one that doesn't need a server to run it. If quick and easy documentation is what you're after, then Bdoc could be the one for you.

Fancy a new theme?

Mislav Marohnic, author of the great will_paginate plugin, has a great theme for RDoc called Hanna. With its familiar three panes on the left for navigation, and a neat ajax search field for methods, this theme brings your RDocs up to date.

Post by Matthew Lang - Matthew Lang is an ERP developer with a keen interest in Ruby and Rails programming.

Comments

  1. David Dai says:

    I have to say my favorite is sdoc: http://github.com/voloko/sdoc/tree/master a.k.a. http://www.railsapi.com/ Using it with Fluid (http://fluidapp.com/) on the Mac is just pure awesome!

  2. raggi says:

    With regard to the new theme, you can actually just install the latest rdoc.

    gem install rdoc for 2.4.x+, and it comes with the darkfish generator.

    It's also quite a bit faster.

  3. stainless says:

    I prefer hanna than darkfish

    I think rdoc should hanna as default template

  4. seydar says:

    Should YARD (http://github.com/lsegal/yard/tree/master) be noted for this category? It's an alternative doc generator to RDoc, and it lets you do some damn cool things with your code.

  5. Matthew Lang says:

    Thanks for the link Seydar. I'll be sure to check that one out!

  6. Jan Wedekind says:

    I use NaturalDocs to document HornetsEye. NaturalDocs optionally supports frames but doesn't require them. In contrast to Doxygen (which does not support Ruby) it does not support custom HTML code and named hyperlinks.

  7. Josh says:

    So what's available for the poor soul who would hope to never touch a browser but loves man(1) and info(1)?

Other Posts to Enjoy

Twitter Mentions