Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Moved all documentation from pyref.vim to README.md
  • Loading branch information
xolox committed Jun 3, 2010
1 parent bf6751d commit 218990f
Show file tree
Hide file tree
Showing 2 changed files with 108 additions and 87 deletions.
124 changes: 92 additions & 32 deletions README.md
@@ -1,49 +1,109 @@
The file [pyref.vim][formatted_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 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 `lynx` or `w3m` will be
used, otherwise the plug-in prefers a graphical web browser like Mozilla
Firefox or Google Chrome.
# Context-sensitive documentation <br> for Python source code in Vim

The file [pyref.vim] [view_plugin] is a plug-in for the [Vim text editor]
[vim_homepage] that maps the `<F1>` key in [Python] [python_homepage] buffers
to search through the [Python language reference] [pylangref] and [library
reference] [pylibref] 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 `lynx` or `w3m` will be used,
otherwise the plug-in prefers a graphical web browser like Mozilla Firefox or
Google Chrome.

## 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 [create-index.py][formatted_create_index_py])
or you can download the index that I've already created (see [vimpythonindex][formatted_vimpythonindex]).
yourself using a Python script I've written (see the file [create-index.py]
[view_spider]) or you can download the index that I've already created (see
the file [vimpythonindex] [view_index]).

## Usage and options

[formatted_pyref_vim]: http://github.com/xolox/vim-pyref/blob/master/pyref.vim
[formatted_create_index_py]: http://github.com/xolox/vim-pyref/blob/master/create-index.py
[formatted_vimpythonindex]: http://github.com/xolox/vim-pyref/blob/master/vimpythonindex
Right-click and save the file [pyref.vim][download_plugin] 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][download_index] as `~/.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 `<F1>`
key. If it doesn't work at first, please see the `pyref_browser` and
`pyref_mapping` options below.

USAGE
=======
The following paragraphs explain the available options:

Right-click and save [pyref.vim][raw_pyref_vim] as `~/.vim/plugin/pyref.vim`
(if you're on Windows save the file as `%USERPROFILE%\vimfiles\plugin\pyref.vim`),
likewise save [vimpythonindex][raw_vimpythonindex] as `~/.vimpythonindex` (if
you're on Windows then save this file as `%USERPROFILE%\_vimpythonindex`) and
restart Vim. Now try it out: Open some Python source code in Vim and press the
`<F1>` key. If it doesn't work out of the box you probably need to change the
global variable `pyref_browser` to the filename or pathname of a working web
browser executable, e.g. inside Vim type:
### The `pyref_browser` option

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'

[raw_pyref_vim]: http://github.com/xolox/vim-pyref/raw/master/pyref.vim
[raw_vimpythonindex]: http://github.com/xolox/vim-pyref/raw/master/vimpythonindex
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:

:let pyref_browser

### The `pyref_mapping` option

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 `pyref_mapping`
according to the syntax expected by Vim's `:imap` and `:nmap` commands:

:let pyref_mapping = 'K'

Note that setting `pyref_mapping` won't change the mapping in existing buffers.

### The `pyref_mirror` option

CONTACT
=========
The option `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 `/usr/share/doc/python2.6/html/`
which happens to be the default location checked by the [pyref.vim]
[view_plugin] script. If you've installed the documentation elsewhere, change
the global variable `pyref_mirror` accordingly.

### The `pyref_index` option

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, `%USERPROFILE%` on
Windows).

### 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 `%USERPROFILE%\_vimrc`
script (on Windows). If you set `pyref_browser` and/or `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.

## Contact

If you have questions, bug reports, suggestions, etc. the author can be
contacted at <peter@peterodding.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 you can vote for it on [vim.org][vim_scripts_entry].
If you like the script please vote for it on [vim.org][vim_scripts_entry].

[vim_scripts_entry]: http://www.vim.org/scripts/script.php?script_id=3104
## License

LICENSE
=========
Vim-PyRef is licensed under the [MIT license] [mit_license].<br>
© 2010 Peter Odding &lt;<peter@peterodding.com>&gt;.

Vim-PyRef is licensed under the MIT license.
Copyright 2010 Peter Odding <peter@peterodding.com>.

[download_index]: http://github.com/xolox/vim-pyref/raw/master/vimpythonindex
[download_plugin]: http://github.com/xolox/vim-pyref/raw/master/pyref.vim
[mit_license]: http://en.wikipedia.org/wiki/MIT_License
[pylangref]: http://docs.python.org/reference/index.html
[pylibref]: http://docs.python.org/library/index.html
[python_homepage]: http://python.org/
[view_index]: http://github.com/xolox/vim-pyref/blob/master/vimpythonindex
[view_plugin]: http://github.com/xolox/vim-pyref/blob/master/pyref.vim
[view_spider]: http://github.com/xolox/vim-pyref/blob/master/create-index.py
[vim_homepage]: http://www.vim.org/
[vim_scripts_entry]: http://www.vim.org/scripts/script.php?script_id=3104
71 changes: 16 additions & 55 deletions pyref.vim
@@ -1,49 +1,10 @@
" Vim plug-in
" Maintainer: Peter Odding <peter@peterodding.com>
" Last Change: June 1, 2010
" Last Change: June 3, 2010
" URL: http://peterodding.com/code/vim/pyref
" License: MIT

" Description:
" This is a Vim plug-in that maps <F1> in Python buffers to search the Python
" language and library reference documentation for the keyword or identifier
" at the current cursor position and open the first match in your web browser.
" This should work in both graphical Vim and console Vim. 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 or you can download an index that I'm making
" available based on http://docs.python.org/.
"
" Configuration options:
"
" "pyref_mapping": If you don't want this plug-in to use the <F1> key then
" you can change this global variable according to the
" syntax expected by :imap and :nmap.
" "pyref_browser": If the plug-in doesn't work out of the box you might have
" to change this global variable to the filename or pathname
" of your web browser (the plug-in tries to find a sensible
" default but that might not always work).
" "pyref_index": Set this global variable to change the location of the
" index file from its default (on Windows the default is
" "~/_vimpythonindex", on UNIX it is "~/.vimpythonindex").
" "pyref_mirror": Sometimes I don't have an internet connection available,
" therefor I've installed the Ubuntu package `python2.6-doc'
" which puts the Python language and library reference in
" /usr/share/doc/python2.6/html/. If you're using the exact
" same package everything should just work, but if you've
" installed the Python documentation in another location
" you should set this global variable to the pathname of the
" directory containing the HTML files.
"
" Note that you can change any of these options permanently by putting the
" relevant :let statements in your ~/.vimrc script.
"
" Tweaks:
" You can improve Vim's startup speed slightly by setting the global variables
" "pyref_browser" and/or "pyref_mirror" in your ~/.vimrc because that avoids
" querying the file system and searching the $PATH.

" Define the configuration defaults.
" Configuration defaults. {{{1

if !exists('pyref_index')
if has('win32') || has('win64')
Expand Down Expand Up @@ -103,13 +64,13 @@ if !exists('pyref_browser')
endif
endif

" Use an automatic command to map <F1> only inside Python buffers.
" Automatic command to define key-mapping. {{{1

augroup PluginPyRef
autocmd! FileType python call s:DefineMappings()
augroup END

function! s:DefineMappings()
function! s:DefineMappings() " {{{1
let command = '%s <silent> <buffer> %s %s:call <Sid>PyRef()<CR>'
" Always define the normal mode mapping.
execute printf(command, 'nmap', g:pyref_mapping, '')
Expand All @@ -120,16 +81,7 @@ function! s:DefineMappings()
endif
endfunction

" This list of lists contains [url_format, method_pattern] pairs that are used
" to recognize calls to methods of objects that are one of Python's standard
" types: strings, lists, dictionaries and file handles.
let s:object_methods = [
\ ['library/stdtypes.html#str.%s', '\.\@<=\(capitalize\|center\|count\|decode\|encode\|endswith\|expandtabs\|find\|format\|index\|isalnum\|isalpha\|isdigit\|islower\|isspace\|istitle\|isupper\|join\|ljust\|lower\|lstrip\|partition\|replace\|rfind\|rindex\|rjust\|rpartition\|rsplit\|rstrip\|split\|splitlines\|startswith\|strip\|swapcase\|title\|translate\|upper\|zfill\)$'],
\ ['tutorial/datastructures.html#more-on-lists', '\.\@<=\(append\|count\|extend\|index\|insert\|pop\|remove\|reverse\|sort\)$'],
\ ['library/stdtypes.html#dict.%s', '\.\@<=\(clear\|copy\|fromkeys\|get\|has_key\|items\|iteritems\|iterkeys\|itervalues\|keys\|pop\|popitem\|setdefault\|update\|values\)$'],
\ ['library/stdtypes.html#file.%s', '\.\@<=\(close\|closed\|encoding\|errors\|fileno\|flush\|isatty\|mode\|name\|newlines\|next\|read\|readinto\|readline\|readlines\|seek\|softspace\|tell\|truncate\|write\|writelines\|xreadlines\)$']]

function! s:PyRef()
function! s:PyRef() " {{{1

" Get the identifier under the cursor including any dots to match
" identifiers like `os.path.join' instead of single words like `join'.
Expand Down Expand Up @@ -196,7 +148,16 @@ function! s:PyRef()

endfunction

function! s:JumpToEntry(lines, pattern)
" This list of lists contains [url_format, method_pattern] pairs that are used
" to recognize calls to methods of objects that are one of Python's standard
" types: strings, lists, dictionaries and file handles.
let s:object_methods = [
\ ['library/stdtypes.html#str.%s', '\.\@<=\(capitalize\|center\|count\|decode\|encode\|endswith\|expandtabs\|find\|format\|index\|isalnum\|isalpha\|isdigit\|islower\|isspace\|istitle\|isupper\|join\|ljust\|lower\|lstrip\|partition\|replace\|rfind\|rindex\|rjust\|rpartition\|rsplit\|rstrip\|split\|splitlines\|startswith\|strip\|swapcase\|title\|translate\|upper\|zfill\)$'],
\ ['tutorial/datastructures.html#more-on-lists', '\.\@<=\(append\|count\|extend\|index\|insert\|pop\|remove\|reverse\|sort\)$'],
\ ['library/stdtypes.html#dict.%s', '\.\@<=\(clear\|copy\|fromkeys\|get\|has_key\|items\|iteritems\|iterkeys\|itervalues\|keys\|pop\|popitem\|setdefault\|update\|values\)$'],
\ ['library/stdtypes.html#file.%s', '\.\@<=\(close\|closed\|encoding\|errors\|fileno\|flush\|isatty\|mode\|name\|newlines\|next\|read\|readinto\|readline\|readlines\|seek\|softspace\|tell\|truncate\|write\|writelines\|xreadlines\)$']]

function! s:JumpToEntry(lines, pattern) " {{{1
let index = match(a:lines, a:pattern)
if index >= 0
let url = split(a:lines[index], '\t')[1]
Expand All @@ -206,7 +167,7 @@ function! s:JumpToEntry(lines, pattern)
return 0
endfunction

function! s:OpenBrowser(url)
function! s:OpenBrowser(url) " {{{1
let browser = g:pyref_browser
if browser =~ '\<\(lynx\|links\|w3m\)\>'
execute '!' . browser fnameescape(a:url)
Expand Down

0 comments on commit 218990f

Please sign in to comment.