Create an offline version of the Ruby docs

When I began programming Ruby/Rails, I quickly found the online Ruby documentation at ruby-doc.org and the Rails API, which are both very useful. But unfortunately, one cannot be always online. In this blog post, I’ll demonstrate some ways to generate or get the docs offline and some hints on using them.

Ruby

Ruby comes with multiple forms of documentation already installed by default. One quick way to get information about a specific language element is the commandline tool ri. Just type one of the following

ri Classname
ri Classname.classmethod
ri Classname#instancemethod

to get the info you need. If you like ri, you might also checkout the fastri gem, which makes it… faster.

Another format is the RDoc format, a HTML documentation created by the rdoc tool. It works by analyzing the source code. You probably have seen pages generated by the the tool, for example at ruby-doc.org. It is also very easy to use in your own projects. Simply put, all you have to do is to write nice comments above method definitions and then run the rdoc tool.

But back to topic. To create the docs of the ruby-version of your choice, navigate to its source directory and run

rdoc --op path/where/it/should/be/stored

There are also some options to customize the RDoc output. For example you can use -d, which improves the docs with some (really big!) class diagrams. Type rdoc -h to check out the available commands,

When installing a gem, its RDoc and ri-Docs also get installed. The ri integrates, as expected, in the ri-tool. Furthermore, there is a great way to view the RDocs: Just type gem server and point your browser to localhost:8808 ;)

It is also good to know how to use Ruby’s standard library. So why not download it from ruby-doc in a nice format?

Rails

Rails also makes it really easy to create a local copy of the docs. Navigate to a Rails project and type rake rails:doc. The resulting RDoc-pages can be found in the /doc directory.

Alternately, you could, of cause, use the standard method: Running the rdoc binary on the Rails source files.

There are also improved versions (where you don’t need to browser search anymore). I like the one from railsapi.com. Another one is available at railsbrain.com.

You can build the HTML-Docs for all the plugins of a specific Rails project with:

rake rails:doc:plugins

Additionally, there are some cool tutorials hidden in Rails, which can be revealed by the rake task:

rake doc:guides

Conclusion

Get the docs, bookmark them in your browser, continue coding and have fun!:D