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

Note

Activated venv needs to be deactivated before install doq.

This can be automated with vim-plug.

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

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
let g:pydocstring_doq_path = path/to/doq

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 shiftwidth if smarttab is set, otherwise softtabstop. For the latter, you need to set like set softtabstop=4.

Example .vimrc

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

Or:

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

Pydocstring use ftplugin, so filetype plugin on required.

Key map

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

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

Or, if you want disable default keymapping, you can set like following.

let g:pydocstring_enable_mapping = 0

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')

Ignore generate __init__ docstring

If you want ignore to generate __init__ docstring, you can set like following.

let g:pydocstring_ignore_init = 1

Thanks

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