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 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
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 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
Alternately, you could, of cause, use the standard method: Running the rdoc binary on the Rails source files.
You can build the HTML-Docs for all the plugins of a specific Rails project with:
Additionally, there are some cool tutorials hidden in Rails, which can be revealed by the rake task:
Get the docs, bookmark them in your browser, continue coding and have fun!:D