search

danchoi / ri.vim

browse ri documentation from Vim
http://github.com/danchoi/ri.vim
MIT License
114 stars 15 forks source link

readme

ri plugin for Vim

This plugin lets you search and navigate Ruby library and gem documentation inside Vim.

screenshot

Advantages over the venerable ri command-line tool:

Prerequisites

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

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.

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 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

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.

screenshot

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:

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 ,,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

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.

License

MIT