Vim Tips Wiki
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
Tip 556 Printable Monobook Previous Next

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

nnoremap <buffer> K :<C-u>execute "!pydoc " . expand("<cword>")<CR>

or for Windows

nnoremap <buffer> K :<C-u>execute "!C:/<PythonDir>/Lib/ " . expand("<cword>")<CR>

To keep the documentation open while you continue editing, this mapping can be used instead

nnoremap <buffer> K :<C-u>execute "!xterm -e 'pydoc " . expand("<cword>") . "'"<CR>

or for Windows

nnoremap <buffer> K :<C-u>execute "!start cmd /c C:/<PythonDir>/Lib/ " . \|
    \ 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

nnoremap <buffer> K :<C-u>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 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/\'")
  " manually set the path to pydoc
  let s:pydoc_path = "/path/to/python/lib/"

nnoremap <buffer> K :<C-u>let save_isk = &iskeyword \|
    \ set iskeyword+=. \|
    \ execute "Pyhelp " . expand("<cword>") \|
    \ let &iskeyword = save_isk<CR>
command! -nargs=1 -bar Pyhelp :call ShowPydoc(<f-args>)
function! ShowPydoc(what)
  " compose a tempfile path using the argument to the function
  let path = $TEMP . '/' . a:what . '.pydoc'
  let epath = shellescape(path)
  let epydoc_path = shellescape(s:pydoc_path)
  let ewhat = shellescape(a:what)
  " run pydoc on the argument, and redirect the output to the tempfile
  call system(epydoc_path . " " . ewhat . (stridx(&shellredir, '%s') == -1 ? (&shellredir.epath) : (substitute(&shellredir, '\V\C%s', '\=epath', ''))))
  " open the tempfile in the preview window
  execute "pedit" fnameescape(path)

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"
      " otherwise, open the buffer in a split
      execute "sbuffer" bufname
    " create a new buffer, set the nofile buftype and don't display it in the
    " buffer list
    execute "split" fnameescape(bufname)
    setlocal buftype=nofile
    setlocal nobuflisted
    " read the output from pydoc
    execute "r !" . shellescape(s:pydoc_path, 1) . " " . shellescape(a:what, 1)
  " go to the first line of the document

See also



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 (or a local mirror on your file system) and showing them in your favorite web browser.