Rdoc for Rails Projects

For those that don’t know, RDoc is the infamous substitution Ruby developers throw out there for “getting started”. RDoc will read code from your Ruby files, and build meaningful output in the form of HTML, chm (Windows help files), RI, and XML. The most common appearance of RDoc for me has been the HTML output. And example of this format can be found on RDoc’s page

I was recently trying to generate documentation for a Rails application that I wrote, however I couldn’t find the documentation for the built in “rake doc:app” task. My complaint with the default options is that it documents the entire Rails framework, including any gems you have included, etc. This is typically WAY TOO MUCH INFORMATION. Considering that Rails is a framework with its own documentation, combining its documentation in with your documentation doesn’t seem like a good idea. If I want to view how ActiveRecord works, I would go to http://api.rubyonrails.org/classes/ActiveRecord/Base.html, not to my generated RDoc collection.

I decided not to use the rake task, and want back to RDoc (since they have a man page) to see what my available options are. “doc:app” just calls RDoc anyways. I found that RDoc will allow you to build documentation based on a directory, instead of the whole she-bang. From the man page:

“rdoc [options] [names…]

If a name is a directory, it is traversed. If no names are specified, all Ruby files in the current directory (and subdirectories) are processed. This means that we can issue a command to look at just the “app/” folder of our project (where the majority of our created code resides) with this command:

# (From inside the Rails root directory)
rdoc -o doc/ app/*

This will create our output at doc/. Inside this directory, you will see an index.html file allowing you to build your class.

If you want to exclude files, or directories, you can use the argument “-x”. If you want to include other working directories, you can use the “-i” argument.

Here are a few other interesting things to try with RDoc:

• –all – This will generate documentation for public AND private methods. By default, RDoc skips the private methods. This can be used to generate internal, and external documentation, where more or less information is exposed.
• –diagram – This requires some additional libraries, but it promises to generate visual graphics that show your classes and modules. You will need to install graphviz first.
• –line-numbers – Helpful for internal documentation, and for tasks like debugging
• –style – You can specify your own CSS file for custom styles

As for formatting your comments, take a look at the RDoc official docs (created with RDoc!). There is a section on Markup syntax. It is very similar to the Wiki markup syntax.