ri plugin for Vim
This plugin lets you search and navigate Ruby library and gem documentation inside Vim.
Advantages over the venerable ri command-line tool:
- write code and browse pertinent documentation in adjacent Vim windows
- search with autocompletion help
- hyperlinking lets you jump from definition to definition
- run back and forth through your jump history with CTRL-o and CTRL-i
- jump directly to gem READMEs and into the gem source directories
- directly open corresponding HTML-formatted rdoc documentation
Prerequisites
- Ruby 1.9.2 or higher
- Vim 7.3 (will not work correctly on 7.2)
- rdoc 3.8 or higher
Install
Copy the contents of plugin/ into your .vim/plugin directory.
Commands
For 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
,ropens the search/autocomplete window, and will use a horizontal split to display matching documentation,Ropens the search/autocomplete window, and will use a vertical split to display matching documentatoin,Kopens the search/autocomplete window and prefills it with the keyword under the cursorKis automatically remapped to use ri.vim if the current buffer is a *.rb file
If these mappings clash or you don't like them, you can override some of them. See Changing keymappings below.
Using the search/autocomplete window
With 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.
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.
Use the standard Vim autocompletion commands to move up and down the match list.
CTRL-pandCTRL-nlet you navigate the drop-down matches. PressENTERto select one.CTRL-ecloses the match list and lets you continue typingCTRL-u: when the match list is active, cycles forward through the match list and what you've typed so far; when the match list is inactive, erases what you've typed.- both
TABandCTRL-x CTRL-ureactivate autocompletion if it's gone away CTRL-yselects the highlighted match without triggering ENTER
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 have a "comment" associated with them. (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
,,rinvokes the class/module method autocompletion window-goes up from a method page to the page of the parent class or moduleCTRL-oandCTRL-ijump you back and forward through the documentation pages you've visited
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,
displayed in a Vim window.
You can move the 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 ,,r. This brings up the class/module method
autocompletion window:
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:
When you are looking at the documentation for an instance or class method, you
can still use ,,r 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
,gtakes you to the README of the gem, if you're looking at documentation for a gem,hopens the HTML RDoc version of the gem documentation you are looking at
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.
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.
To generate ri documentation for your gems, use these commands:
# for global gems
gem list | tr -d '(,)' | awk '{print $1, "--version", $2}' | xargs -n3 gem rdoc --ri --no-rdoc
# for bundled gems
bundle list | tr -d '*(,)' | awk '{print $1, "--version", $2}' | xargs -n3 gem rdoc --ri --no-rdoc
If you like using ri.vim, you may want 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
Alternatively you can also disable the default plugin mappings to set your own:
let g:ri_no_mappings=1
Maintainers
Acknowledgements
Thanks to Eric Hodel for developing the ri and rdoc infrastructure that ri.vim builds on. ri.vim adds just a little piece to that very useful codebase.
Thank you to Suraj Kurapati for the tip on how to generate ri documention for installed gems.
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.
- Twitter: @danchoi
- Personal Email: [email protected]
- My Homepage: http://danielchoi.com/software