ri.vim : ri plugin for Vim

ri.vim lets you search and navigate Ruby library and gem documentation inside Vim.

Advantages over the venerable ri command-line tool:

Please check out my related Vim plugin RbNav for project-navigation features.

Prerequisites

Install

gem install ri_vim && ri_vim_install

This installs the ri.vim plugin into your ~/.vim/plugin directory.

To upgrade ri.vim to a newer version, just repeat the installation procedure.

The next step is to make sure that you have ri documentation installed on your system for everything you want to look up. See the How to generate ri documentation section below for help.

Commands

For the all the commands below, the mapleader is assumed to be ,. If it is \ or something else for your setup, use that instead.

Invoking the plugin

If these mapping clash or you don't like them, you can override some of them. See Changing keymappings below.

Using the search/autocomplete window

Withe the search/autocomplete window open, start typing the name of the class, module, or method you want to lookup.

Press TAB to start autocompletion.

If you've started typing a name starting with a capital letter, you'll see autocompletion suggestions for matching classes and modules. If you're looking for a namespace-nested module or class, you can autocomplete the first namespace, type : and then press TAB again to autocomplete the next inner namespace.

screenshot

If you've started typing a name starting with a lower case letter or a symbol that is valid in Ruby method names (i.e., /^[=*\/&|%^\[<>]/), ri.vim will suggest matching methods from different classes and modules.

screenshot

Use the standard Vim autocompletion commands to move up and down the match list.

When you're searching for a class or module (but not yet for method searches), you will sometimes see a little number in parentheses to the right of a match. This is a rough indicator of how much actual documentation there is to see for that class or module. It actually represents how many "parts" of the generated documentation has a "comment" associated with it. (Don't ask me what the definition of a "part" is; it's just something the RDoc::RI codebase knows about.) Please note that the relationship between the number of comment-parts and the length of the documentation is not exactly linear. But it's still a useful filter for knowing which documentation pages are worth looking up.

The documentation window

When you find a matching method or class or module and press ENTER, you should see the ri documentation, with a light touch of color-highlighting, display in a Vim window.

screenshot

You can move to cursor to any valid Ruby method or class/module name on this page (including the class and instance methods at the bottom) and press ENTER to jump to the documentation.

You can also find a method on any class or module you're looking at the documentation for by pressing ,rr. This brings up the class/module method autocompletion window:

screenshot

Here you can just start typing the method name (you don't need to indicate whether it is a class or instance method) and press TAB. Then the match list should narrow down your choices quickly. Again, the numbers here are a very rough indicator of how much documentation there is to see for that method.

Let's look at #encode:

screenshot

When you are looking at the documentation for an instance or class method, you can still use ,rr to browse and jump to other methods on that same class or module.

You can also use - to jump up the hierarchy to the page for the String class. If you were in a nested class, e.g. File::Stat, you could also jump up to File with -.

Alternatively, you can use the standard Vim command CTRL-o to jump back to where you were before you jumped to this page. CTRL-i takes you back forward.

Gem READMEs and HTML RDocs

If you are looking at documentation for a Gem, you can see the README for that gem (assuming it exists and is called README.*) by pressing ,g.

If you've generated the HTML RDoc documentation for this Gem, you can open it in a web browser by pressing ,h.

If you're looking at a gem's README, you can change the local working directory to the gem root directory by using the vim command :lcd %:h.

How to generate ri documentation

ri.vim won't work very well unless you have generated ri documentation for your Ruby built-in library, standard library, and your installed Ruby gems.

Please consult other reference sources for instructions specific to your particular setup.

But I'll try to cover some common cases:

If you use RVM, run this to install ri documentation for the built-in and standard library of your active Ruby installation:

rvm docs generate-ri

You can check if this worked by running a command like ri Enumerable or ri IO on the command line.

You may run into the following an error when you run this rvm command:

uh-oh! RDoc had a problem:
invalid option: --ri-site generator already set to ri

If you see this, my solution (I'm not 100% sure this is the best way) was to patch the ~/.rvm/scripts/docs script. Find the generate_ri() function and replace this line:

rdoc -a --ri --ri-site > /dev/null 2>> ${rvm_log_path}/$rvm_docs_ruby_string/docs.log

with:

rdoc -a --ri 

This should let you run rvm docs generate-ri successfully.

To generate ri documentation for your gems, reinstall the ones currently without ri documentation with the following command

gem install [gemname] --ri

and then check to see if this worked by using ri to look up a class or module in that gem; e.g.,

ri ActiveRecord::Associations::ClassMethods

If you like using ri.vim, you may want to make to remove --no-ri if you added that to your .gemrc. This will make sure that the gem install command automatically generates ri documentation.

Changing keymappings

You can change the keymappings for invoking ri.vim by appending something like this to your .vimrc:

nnoremap  ,ri :call ri#OpenSearchPrompt(0)<cr> " horizontal split
nnoremap  ,RI :call ri#OpenSearchPrompt(1)<cr> " vertical split
nnoremap  ,RK :call ri#LookupNameUnderCursor()<cr> " keyword lookup 

Acknowledgements

Special thanks to Eric Hodel for developing and maintaining the whole ri and rdoc infrastructure that ri.vim builds on. ri.vim adds just a little piece to that very useful codebase.

Bug reports and feature requests

Please submit them here:

About the developer

My name is Daniel Choi. I specialize in Ruby, Rails, MySQL, PostgreSQL, and iOS development. I am based in Cambridge, Massachusetts, USA.