2

I've recently decided to give Vim a try and am trying to get it set up for work with Python.

I've installed YCM, so I have autocompletion now, which is good, but there are a few things documentation-wise that I'd like to have set up.

K will open up a window beautifully which can be closed easily with :q. I really like that, but a big problem is that it only seems to work for official documentation. That is, if the cursor is on a function imported from a standard library module, say, range, timeit etc, everything goes as expected.

But if import one of my own modules, even if I define doctrings for a function or class or method, or the module itself, K will tell me there's no documentation to be found. How can I solve this so as to be able to pull the documentation for my own code or code outside the official stdlib one?

The second thing is related to the first: it's about docstrings. In Emacs when the cursor was on anything that had a docstring (whether standard library or some personal module, or something defined in the current file), it would display it in the minibuffer (i.e. where you type in ex commands in vim). The question here is, how do I make it so that the docstring of a function/method/whatever is printed out (whether in the 'minibuffer', or in a popup or some other way)?

Any help would be much appreciated

  • 2
    Welcome to this site Daniel. Could you edit your question so that it's easier to understand what you want to do? What do you mean by "displaying a docstring"? What is the current behavior and what is your expected behavior? In which case do you want to display this docstring? – statox Aug 5 at 12:03
  • 2
    No need to be sorry don't worry :) A few last things: When you say that ctrl+k opens a window with the doc I think you instead mean K (or shift+k), right? Or maybe you have a custom configuration. I think vim-jedi has an improved support of keywordprg (which is what is triggered by K, :h K) but I rarely use python so other people on here will probably have better suggestions. – statox Aug 5 at 12:52
  • 1
    Yes, you're right. Reedited it to correct that – Daniel Aug 5 at 13:03
  • 1
    @Daniel if you’ve solved your problem, please add an answer! That helps others too :) but yes in this case I would have said you need to coordinate with the keywordprg. Re popup, you could use the cursorhold event to try to open one—you’d have to close it intelligently, but that can probably be done – D. Ben Knoble Aug 6 at 14:19
  • 1
    YCM can show docsting for word under cursor in preview window. Why not use it? nnoremap <F1> :silent YcmCompleter GetDoc<CR>? And one more to close window: nnoremap <S-F1> :pclose<CR> – Dmitry Aug 8 at 14:45
2

What program is called when K is pressed is set by keywordprg. By default, this is set to man (the linux manual). Changing it to pydoc so as to get Python documentation will do the trick, but then you don't the manual being checked anymore - which is an issue if, for example, you're working with C code, as C's library code has documentation in the man system so you wouldn't be getting that.

So one would want to have pydoc being used when working with python, and leave man as the default for when C files are being edited.

The autocmd BufNewFile,BufRead bit below accomplishes that.

So here's what I have in my .vimrc:

autocmd BufNewFile,BufRead *.py set keywordprg=pydoc3.8

This will set keywordrg to pydoc only when opening a file ending in .py or reading it from a buffer.

Note that simply specifying 'pydoc' will use whatever version of pydoc is set by the system for that name. That is, pydoc has multiple versions that are tied to Python's: pydoc2.7, pydoc3.3, etc. 'pydoc', much like 'python' - unqualified - rely on the alternatives linux system, where the name is essentially a soft link to an actual binary version. In my case pydoc pointed to relatively old version, and while that could be easily changed with update-alternatives it's arguably easiest and more convenient to just specify the desired version, like I did above - i.e. pydoc3.8.

Docstrings

The docstrings show up when moving through the autocompletion suggestions. They will appear at the top of the screen, in a small preview window. One can completely disable the window (which I'd done, that being the reason I wasn't seeing any docstrings), make it automatically close when a suggestion is accepted and more. See here .

Personally, I left it in place and set a key mapping to have it closed when pressing f4 in either insert or visual mode.

However, to get a docstring - that is, to make it show up in the preview window - (however rare that case may be), I have to actually go put the cursor on the target word and force the autocompletion list to pop up by pressing Ctrl Space. Ideal would be for this to happen on CursorHold, without having to press anything, though since I'm so new to Vim myself, I haven't yet been able to figure that out.

| improve this answer | |
  • 3
    Instead of using an autocmd for files matching *.py, you can also use autocmd Filetype python which will match files detected as Python. You can also place commands such as setlocal keywordprg=pydoc3.8 inside a file ~/.vim/after/ftplugin/python.vim, in which case Vim will do the autocmd part for you. Also note that it's likely you actually need setlocal instead of set, to only set the option for the current buffer and not for Vim globally. – filbranden Aug 7 at 1:58
  • 1
    thanks a lot for the tips – Daniel Aug 7 at 6:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.