addons/pydoc/plugin/pydoc.vim

   1 " pydoc.vim 0.4 (initial public version)
   2 " Allow the user to pull pydoc information into Vim
   3 " Mike Repass <theopenroad@gmail.com>
   4 " October 2004
   5
   6 " USAGE:
   7 " Put this in ftplugin/python/ or just manually source it using a FileType
   8 " autocommand in your vimrc. It registers the command Pydoc (try ':Pydoc re'
   9 " for regular expression docs). Also, it remaps K so that you can position the
  10 " cursor over a module or module.method etc and hit K to bring up the docs.
  11 " Make sure PYDOC_CMD points to the pydoc script. I use a 'pydoc.bat' batch
  12 " file on my WinXP system.
  13 "
  14 " A nice little side effect of using this is that the documentation buffers
  15 " become sources for keyword completion. For instance, say you're working on a
  16 " program that uses urllib2 and you're having trouble remembering the methods.
  17 " Simply do a ':Pydoc urllib2' and close the window. The buffer will remain
  18 " hidden and Ctrl-N and Ctrl-P will pick up all the text when you need to
  19 " complete.
  20 "
  21 " Btw just doing ':Pydoc modules' should bring up a list of all available
  22 " modules. Very handy just to leave open, as you can now just press 'K' over a
  23 " module to load it up.
  24
  25 " NOTES:
  26 " The 'cleanest' or most 'pythonic' way to do this would be use the
  27 " vim-python interface and write some supporting python code to manually
  28 " import pydoc and call the associated functions. However, I don't always use
  29 " the version of python for which my vim is compiled, so I decided to
  30 " externally call the pydoc script.  Also, it sets up the buffers to go
  31 " 'hidden' when closed, so that when you do the same Pydoc command again, it
  32 " will load the buffer and thus avoid the overhead of the external call
  33 " (basically a cheap cache system). If you don't want this, set the NO_HIDE
  34 " option to 1.
  35
  36 " BUGS:
  37 " I am not aware of any major bugs, but of course there are some minor
  38 " interface glitches. For instance, if you put the cursor over an operator
  39 " which also has significance in your particular shell, invoking the command
  40 " might result in a shell error. I feel having some little 'oopses' like this
  41 " is pretty inevitable, but I'll be happy to work on anything that causes you
  42 " problems. If you come across any bug you feel impairs your ability to use
  43 " Vim, drop me an email and I'll get right on it.
  44
  45 " OPTIONS:
  46 let s:PYDOC_CMD = "pydoc" " this must point to the pydoc script
  47 let s:NO_HIDE = 0 " when 1, pydoc buffers will be deleted (instead of hidden)
  48
  49 " command interface
  50 com! -nargs=+ Pydoc call <SID>:PydocLoad("<args>")
  51
  52 " remap the K (or 'help') key
  53 nnoremap <silent> <buffer> K :call <SID>:KeyPydocLoad(expand("<cWORD>"))<Cr>
  54
  55 " prepares the cWORD argument for PydocLoad...
  56 func! <SID>:KeyPydocLoad(cword)
  57         " make sure we got something
  58         if a:cword == ""
  59                 return
  60         endif
  61         " we want the current WORD just up to the first parenthesis
  62         " this allows us to get math.acos from math.acos(.2) etc
  63         let prep = substitute(a:cword, "\(.*", "", "")
  64         call <SID>:PydocLoad(prep)
  65 endfunc
  66
  67 " opens a new buffer, filling it with the result of calling pydoc with pyargs
  68 func! <SID>:PydocLoad(pyargs)
  69         " first, check if we've already loaded the pydoc info for this search and
  70         " if so, open it and bail... this creates an ad hoc caching mechanism
  71         let window_name = "pydoc - " . a:pyargs
  72         if bufloaded(window_name)
  73                 exec "new " . window_name
  74                 return
  75         endif
  76
  77         " build and execute the command
  78         let cmd = "new +r!" . escape(s:PYDOC_CMD," ")   " new buff, call pydoc
  79         let cmd = cmd . "\\ " . escape(a:pyargs," ")    " the pydoc args
  80         let cmd = cmd . " " . window_name                               " the name of the window
  81         try
  82                 silent exec cmd
  83         catch
  84                 redraw |
  85                 \ echohl WarningMSG |
  86                 \ echomsg "Error occurred while attempting to invoke Pydoc." |
  87                 \ echohl None
  88                 return
  89         endtry
  90
  91
  92         " make sure the command succeeded and we're in the right buffer
  93         if bufname("") != "pydoc - " . a:pyargs
  94                 " hmmm something didn't work... lets bail
  95                 return
  96         endif
  97
  98         " roll back, delete empty lines at beginning
  99         normal gg
 100         while getline(1) =~ "^\s\*$"
 101                 normal dd
 102         endwhile
 103
 104         " set some convenient options to avoid error messages etc
 105         setlocal nomodifiable
 106         setlocal buftype=nowrite
 107         setlocal bufhidden=hide
 108         if s:NO_HIDE
 109                 setlocal bufhidden=delete
 110         endif
 111
 112         " bail if no documentation was found
 113         if getline(1) =~ "^no Python documentation found"
 114                 redraw |
 115                         \ echohl WarningMsg |
 116                         \ echomsg "No Python documentation for " . a:pyargs |
 117                         \ echohl None
 118                 setlocal bufhidden=delete
 119                 quit
 120                 return
 121         endif
 122
 123         " key map to these functions for these buffers
 124         nnoremap <silent> <buffer> K :call <SID>:KeyPydocLoad(expand("<cWORD>"))<Cr>
 125
 126         " some _very_ basic syntax highlighting
 127         syn match pydocTitle "^[A-Z]\+$"
 128         hi link pydocTitle Tag
 129
 130 endfunc