for Python source code in Vim
pyref.vim script is a plug-in for the Vim text editor that helps you look up the documentation for keywords and identifiers from the following sources using your web browser:
:PyRef command looks up the identifier given as an argument while the
<F1> mapping (only available in Python buffers) looks up the item under the text cursor. The lookup works by scanning through a special index file which is included in the ZIP archive below, but you can also create/update the index yourself using the Python script spider.py.
Install & usage
Unzip the most recent ZIP archive file inside your Vim profile directory (usually this is
~/.vim on UNIX and
%USERPROFILE%\vimfiles on Windows), restart Vim and execute the command
:helptags ~/.vim/doc (use
:helptags ~\vimfiles\doc instead on Windows). Now try it out: Open a Python script and press the
<F1> key on something interesting. If it doesn't work or you want to change how it works, see the options documented below.
If you press
<F1> and nothing happens you're probably using a terminal that doesn't pass
<F1> through to Vim. In this case you can change the key mapping by setting the global variable
g:pyref_mapping according to the syntax expected by Vim's
:let g:pyref_mapping = 'K'
Note that setting
g:pyref_mapping won't change the key mapping in existing buffers.
This option is useful when you don't always have a reliable internet connection available while coding. Most Linux distributions have an installable package containing the Python documentation, for example on Ubuntu and Debian you can execute the following command to install the documentation:
$ sudo apt-get install python2.6-doc
The above package puts the documentation in
/usr/share/doc/python2.6/html/ which happens to be the default path checked by the
pyref.vim script. If you've installed the documentation in a different location you can change the global variable
:let g:pyref_python = $HOME . '/docs/python'
This option works like
g:pyref_python but allows you to configure the path to your local Django documentation. On Ubuntu and Debian you can execute the following command to install the Django documentation:
$ sudo apt-get install python-django-doc
In this case you shouldn't have to change anything because
pyref.vim is already configured to be compatible with the
If you don't like the default location of the index file you can change it by setting the global variable
g:pyref_index. A leading
~ in the
g:pyref_index variable is expanded to your current home directory (
$HOME on UNIX,
%USERPROFILE% on Windows). Be aware that when you change the
g:pyref_index option automatic updates using the getscript plug-in won't update the index file anymore!
General note about options
You can change the above options permanently by putting the relevant
:let statements in your vimrc script.
If you have questions, bug reports, suggestions, etc. the author can be contacted at firstname.lastname@example.org. The latest version is available at http://peterodding.com/code/vim/pyref/ and http://github.com/xolox/vim-pyref. If you like the script please vote for it on Vim Online.