Using RDoc

One longstanding weakness with the Ruby community is subpar documentation. I think many Rubyists tend to look down on actual API documentation, preferring instead to just read source code directly. I’ve been guilty of this too and I think some of this is due simply to unfamiliarity with RDoc. Let’s change that now.

Creating RDoc

I’ve never found an easily accessible RDoc markup reference. The only one I know of is unlinkable, buried at the bottom of the RDoc readme instead of front and center as it should be. So I extracted the RDoc markup reference for your reading pleasure. Jan Varwig created a great RDoc cheatsheet PDF for local or offline access.

Next time you’re working on a gem, take 10 minutes to read the reference and document the main class for the gem. It’ll make you a better Rubyist, I guarantee it.

Generating RDoc

Ok, so you’ve learned RDoc markup and your code is documented like a champ. What do you do now? You’ve got several choices:

  • Generate rdoc by hand – the rdoc command ships with Ruby and by default generates all .rb files in or below the current directory. You probably want something like rdoc lib to just include your project’s main Ruby code.
  • Integrate RDoc into Rake – Rake has an RDocTask which can be configured for your project, so you can just run rake rdoc.

Once generated, you can view the generated output at doc/index.html.

Viewing RDoc

Rubygems has built-in support for generating and viewing the RDoc for installed gems. rdoc is generated when the gem is installed (using gem install --no-rdoc [name] skips the local rdoc generation). You can then use gem server to view your local gem rdoc at http://localhost:8808.

Check out YARD

YARD is an interesting project by Loren Segal to create a next generation Ruby documentation system. Getting started with YARD is well documented; try it out if you want an alternative to RDoc. YARD’s syntax is a superset of RDoc’s so backwards compatibility should not be an issue. The generated documentation looks pretty awesome (note the support for Markdown-formatted README files, which RDoc does not have).

The YARD team also created RubyDoc.info, which hosts documentation for popular gems and is a great resource for finding linkable documentation.

I hope this helps de-mystify rdoc for people. Any other rdoc tips, please leave a comment. Happy documenting!

6 thoughts on “Using RDoc”

  1. If you’re building a gem *and* using rake’s RDocTask, beware the duplication of rdoc settings between the two. (Your local `rake rdoc` output may look great, but it’s not necessarily what people will get when they `gem server` and browse.)

    I’ve taken a stab at fixing this (and similar duplication issues) with “shoe,” a small library of rake tasks that take their configuration from the gemspec.

    See further comments at https://github.com/matthewtodd/shoe/blob/v0.7.1/lib/shoe/tasks/rdoc.rb

  2. I agree about the value of documentation. YARD is the best for Ruby in my opinion because of the modularity and the @ tags and [class] tags. Our code documentation improved significantly when we switched from RDoc to YARD.

  3. I’m surprised you think this will demystify rdoc for those of us who aren’t bothering with it.

    We aren’t bothering because we don’t know how to get our docs published along with our gems.

    I’ve written some lovely commentary that gets turned into lovely HTML when I run my rake task. But lo, when I install my gem and then try to look up my docs with the ri utility, I get nothing.

    So I just don’t bother. Your article get me all hot for docs again. I went and worked up rdocs for my magic_options gem. Got 100% rdoc coverage, only to discover that it’s the same old same old.

    Clearly, rdoc is working for a LOT of gem publishers. Just… you know… not the rest of us morons.

  4. It’s amazing how a little vulnerability can galvanize me. On a hunch, I deleted yard, and now when I install my well-documented gem, the ri utility finds its documentation perfectly!

    So thanks for getting me hot for docs again. Well worth the public humiliation. :-)

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>