ri/fastri with rubygems

For some time, I was not able to get ri to read the documentation for the gems that I have installed. There seems to be multiple ways of doing this. I found this site that gives details on the common ways. Some gems are kind enough to automatically install the documentation files by themselves. This makes it possible for ri to detect the documentation for that gem without any further configuration. However, the gems I am most interested in --the Rails gems-- do not do so automatically.

The simplest way to get documentation for all your gems is to run sudo gem rdoc --all. Though this is the simplest method, it is also the one that is most fragile. When you run that command, it must finish the process of generating all the documentation for all your gems. A rogue gem that is improperly configured can mess the entire process up. I discovered this the hard way: the terminal would echo the fact that the documentation for the relevant Rails gems (activesupport, activerecord, etc) have been generated but because there was a failure toward the end, none of them were accessible. Most people will be able to run this command just fine and get the documentation for all the gems. However, when it fails, you can try the method below.

What I am proposing is a more conservative route for generating the documentation: Generate the documentation for each gem on a as-needed-basis. If the gem can automatically generate the documentation for you then you need not run this step at all. For most people, all they need is the documentation for Rails. And if you are using TextMate, having the documentation detected by ri can be most convenient.

Here is what I did. Open two terminal windows. On one do gem list. This gives you a list of all the gems that you have installed. On the other terminal window, do sudo gem rdoc [name_of_gem] where you replace [name_of_gem] with the gem that you are interested in. You can use wilcards such as active* to match activerecord and activesupport. Do this for the gems that you are interested in. This way you avoid generating redundant documentation for gems that are installed as dependencies for other gems.

Finally, if you are still using ri, you might want to take a look at fastri. fastri is supposed to be much faster and more intelligent in its searching capabilities. If you are using fastri, you might need to rebuild the index for the server after generating the documentation. This can be done by running fastri-server -b.