created 2003 · complexity basic · author Fritz Cizmarov · version 6.0
This tip presents several ways to access Python documentation using pydoc. The recommended location for the commands in this snippet is ~/.vim/after/ftplugin/python.vim, or $HOME\vimfiles\after\ftplugin\python.vim on Windows.
Using a shell (simple)
To access Python documentation for the word under the cursor using, this mapping can be used
map <buffer> K :execute "!pydoc " . expand("<lt>cword>")<CR>
or for Windows
map <buffer> K :execute "!C:/<PythonDir>/Lib/pydoc.py " . expand("<cword>")<CR>
To keep the documentation open while you continue editing, this mapping can be used instead
map <buffer> K :execute "!xterm -e 'pydoc " . expand("<cword>") . "'"<CR>
or for Windows
map <buffer> K :execute "!start cmd /c C:/<PythonDir>/Lib/pydoc.py " . \|
\ expand("<cword>")<CR>
These mappings only work for single words. To display the documentation for a method or a class in a module, for example os.popen(), modify the mapping in this way
map <buffer> K :let save_isk = &iskeyword \|
\ set iskeyword+=. \|
\ execute "!pydoc " . expand("<cword>") \|
\ let &iskeyword = save_isk<CR>
It is not recommended to permanently add . to 'iskeyword'.
Using the preview window or a scratch buffer
This snippet allows you to use the command :Pyhelp <string> to preview Python documentation in the preview window. It also remaps K in the same manner as above.
If Vim is compiled with +python, it automatically finds the path to pydoc.py. Otherwise, set the s:pydoc_path variable to a suitable value. This seemingly indirect approach is used in an effort to make the snippet platform agnostic.
if has("python")
" let python figure out the path to pydoc
python << EOF
import sys
import vim
vim.command("let s:pydoc_path=\'" + sys.prefix + "/lib/pydoc.py\'")
EOF
else
" manually set the path to pydoc
let s:pydoc_path = "/path/to/python/lib/pydoc.py"
endif
map <buffer> K :let save_isk = &iskeyword \|
\ set iskeyword+=. \|
\ execute "Pyhelp " . expand("<lt>cword>") \|
\ let &iskeyword = save_isk<CR>
command! -nargs=1 Pyhelp :call ShowPydoc(<f-args>)
function! ShowPydoc(what)
" compose a tempfile path using the argument to the function
let path = $TEMP . '/' . a:what . '.pydoc'
" run pydoc on the argument, and redirect the output to the tempfile
call system(shellescape(s:pydoc_path . " " . a:what . " > " . path))
" open the tempfile in the preview window
execute "pedit " . path
endfunction
If, instead, you prefer using a scratch buffer to the preview window, change the ShowPydoc function to
function! ShowPydoc(what)
let bufname = a:what . ".pydoc"
" check if the buffer exists already
if bufexists(bufname)
let winnr = bufwinnr(bufname)
if winnr != -1
" if the buffer is already displayed, switch to that window
execute winnr . "wincmd w"
else
" otherwise, open the buffer in a split
execute "sbuffer " . bufname
endif
else
" create a new buffer, set the nofile buftype and don't display it in the
" buffer list
execute "split " . bufname
setlocal buftype=nofile
setlocal nobuflisted
" read the output from pydoc
execute "r !" . shellescape(s:pydoc_path . " " . a:what)
endif
" go to the first line of the document
1
endfunction
See also
References
- :help after-directory
- :help :map
- :help :map-<buffer>
- :help :execute
- :help :!
- :help <cword>
- :help 'iskeyword'
- :help :pedit
- :help 'buftype'
Comments
For an alternative approach to the same problem, try the pyref.vim plug-in ( script#3104) which provides context-sensitive documentation for Python source code by looking up help topics on docs.python.org (or a local mirror on your file system) and showing them in your favorite web browser.