README.rst

vim-pydocstring

vim-pydocstring is a generator for Python docstrings and is capable of automatically

• inserting one-line docstrings
• inserting multi-line docstrings

This plugin is heavily inspired by phpdoc.vim and sonictemplate.vim.

Install

Since version 2, vim-pydocstring requires doq.

You can install following command.

$ make install

This can be automated with vim-plug. Activated venv needs to be deactivated before running PlugInstall or PlugUpdate.

Plug 'heavenshell/vim-pydocstring', { 'do': 'make install' }

If you want install doq manually, you can install from PyPi.

$ python3 -m venv ./venv
$ ./venv/bin/pip3 install doq

Then set installed doq path:

$ which doq
g:pydocstring_doq_path

Note

vim-pydocstring support Vim8.

Neovim works since v2.2.0, but if something wrong, send me pull requests to fix it.

If you want use old version checkout 1.0.0

Basic usage

1. Move your cursor on a def or class keyword line,
2. type :Pydocstring and
3. watch a docstring template magically appear below the current line

Format all

type :PydocstringFormat will insert all docstrings to current buffer.

Settings

Pydocstring depends on softtabstop. You need to set like set softtabstop=4.

Example .vimrc

autocmd FileType python setlocal tabstop=4 shiftwidth=4 softtabstop=4 expandtab

Key map

If you want change default keymapping, set following to your .vimrc.

nmap <silent> <C-_> <Plug>(pydocstring)

Formatter

You can set built-in formatter(Sphinx, Numpy, Google).

let g:pydocstring_formatter = 'numpy'

Custom template

You can set custom template. See example.

let g:pydocstring_templates_path = '/path/to/custom/templates'

Exceptions

If you want add exceptions to docstring, create custom template and visual select source block and hit :'<,'>Pydocstring and then excptions add to docstring.

def foo():
    """Summary of foo.

    Raises:
        Exception:
    """
    raise Exception('foo')

Thanks

The idea of venv installation is from vim-lsp-settings. Highly applicate @mattn and all vim-lsp-settings contributors.