5 Reasons You Should Use ri To Read Ruby Documentation
Published on September 13, 2012 by Jesse Storimer
ri is a tool that ships with Ruby. It's a companion to rdoc, allowing you to 'display information about Ruby classes, modules, and methods' from your console. Despite its usefulness it's often overlooked in favour of searching Google.
$ ri File $ ri Fil $ ri File.directory? $ ri Socket#accept $ ri ActiveRecord::Base.touch
Over the last few months I've started using
ri more and more. Once it became part of my workflow I really couldn't believe that I wasn't using it before. And I can't believe you're not using it now!
1. ri Actually Understands Ruby
Something interesting happens when you look for the
$ ri ActiveRecord::Base#save (from gem activerecord-3.2.8) Implementation from ActiveRecord::Persistence [...] (from gem activerecord-3.2.8) Implementation from ActiveRecord::Validations [...]
(I trimmed the output for brevity.)
Notice that it returned documentation from two different modules, neither of which is technically
ActiveRecord::Base. That's because
ri understands that those modules are included into
ActiveRecord::Base so their docs are relevant.
Searching Google for the same thing will not return results that precise.
2. It's Faster Than The Web
Prior to using
ri I would just search Google. This works but adds overhead to what, otherwise, could be a simple lookup on the local filesystem. Going to the web will require at least two network requests (one for the Google Search, one for displaying the documentation site).
Not to mention that I don't have to leave the comfort of my terminal to open a web browser.
3. It's Consistent
There are many different web sites that display Ruby docs. They all display documentation slightly differently, show examples slightly differently, have different sidebars, etc.
ri you get a minimal, consistent interface for reading docs.
4. Interactive Mode
ri with the
-i option. This drops you into an interactive documentation repl. Start typing the classes and methods you're looking for and use <tab> for autocompletion. After reading one set of docs you're returned to the console for more searching.
5. You Already Have It
ri ships with your Ruby install, so you don't need to install anything. The rdoc for core Ruby methods is installed for you when you install Ruby.
So you can start using
ri right away!
Getting ri For All of Your Gems
There's a good chance that, up until now, you've had the following in your
gem: --no-ri --no-rdoc
If you want to use
ri then delete that first option. You can leave
--no-rdoc there, that specifically generates HTML docs. Now any new gems you install will have their
ri docs installed as well.
If you want to generate the missing
ri docs for all your installed gems you can:
$ gem rdoc --all --ri --no-rdoc
I'm happier using
ri for my Ruby documentation needs. Give it a try!
If you know any other tricks leave them in the comments!