for Python source code in Vim
The file pyref.vim is a plug-in for the Vim text editor that maps the
<F1> key in Python buffers
to search through the Python language reference and library
reference documentation for the keyword or identifier at the
current cursor position and open the first match in your web browser. When no
GUI is available a command-line web browser like
w3m will be used,
otherwise the plug-in prefers a graphical web browser like Mozilla Firefox or
How does it work?
The search works by scanning through a special index file with keyword, URL pairs separated by tabs and delimited by newlines. You can create this index yourself using a Python script I've written (see the file create-index.py) or you can download the index that I've already created (see the file vimpythonindex).
Usage and options
Right-click and save the file pyref.vim as
~/.vim/plugin/pyref.vim (if you're on Windows save the file as
%USERPROFILE%\vimfiles\plugin\pyref.vim instead), likewise save the file
~/.vimpythonindex (if you're on Windows
then save this file as
%USERPROFILE%\_vimpythonindex instead) and restart
Vim. Now try it out: Open some Python source code in Vim and press the
key. If it doesn't work at first, please see the
pyref_mapping options below.
The following paragraphs explain the available options:
If the plug-in doesn't work out of the box or you don't like the default web
browser you can change the global variable
pyref_browser to the filename or
pathname of your preferred web browser, e.g. inside Vim type:
:let pyref_browser = '/usr/bin/konqueror'
The plug-in tries to find a suitable default web browser but that might not always work. To see the currently configured web browser type the following:
When you've set
pyref_browser but it still doesn't work you're probably
running Vim inside a terminal which doesn't support
<F1>. In this case you
can change the key-mapping by setting the global variable
according to the syntax expected by Vim's
:let pyref_mapping = 'K'
Note that setting
pyref_mapping won't change the mapping in existing buffers.
pyref_mirror 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
which happens to be the default location checked by the pyref.vim script. If you've installed the documentation elsewhere, change
the global variable
If you don't like the default location of the index file you can change it by
setting the global variable
pyref_index. Note that a leading
~ in the path
is expanded to your current home directory (
$HOME on UNIX,
General note about options
You can change any of the above options permanently by putting the relevant
:let statements in your
~/.vimrc script (on UNIX) or
script (on Windows). If you set
pyref_mirror in your
vimrc this can improve Vim's startup speed slightly because the plug-in won't
have to query the file-system when it's loaded.
If you have questions, bug reports, suggestions, etc. the author can be contacted at email@example.com. 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.org.