How do I display a Python docstring in Vim

Question

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

Answer 1

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.

Answer 2

When vim is compiled with python3, the ftplugin/python.vim that ships with vim will set omnifunc to python3complete#Complete, which will include doc-strings when triggering omni-completion.

With ALE and omnifunc (or completefunc) set to ale#completion#OmniFunc and a completion-compatible language-server installed (ALE supports pylsp, for example—python3 -m pip install pylsp), omni-completion (or user-completion) will show doc-strings.

---

I use completeopt with popup included to use a popup instead of the preview window for docs. Also, with ALE, :ALEHover can give some information. It can now also use a popup with g:ale_hover_to_floating_preview set truthy.

Answer 3

with YouCompleteMe itself you can use :YcmCompleter GetDoc to get full documentation of the object under cursor