https://github.com/heavenshell/vim-pydocstring
Generate Python docstring to your Python source code.
https://github.com/heavenshell/vim-pydocstring
docstring python vim
Last synced: 10 months ago
JSON representation
Generate Python docstring to your Python source code.
- Host: GitHub
- URL: https://github.com/heavenshell/vim-pydocstring
- Owner: heavenshell
- License: bsd-3-clause
- Created: 2012-01-18T12:30:37.000Z (about 14 years ago)
- Default Branch: master
- Last Pushed: 2023-07-15T10:11:43.000Z (over 2 years ago)
- Last Synced: 2025-04-01T22:50:11.752Z (10 months ago)
- Topics: docstring, python, vim
- Language: Vim Script
- Homepage:
- Size: 9.24 MB
- Stars: 337
- Watchers: 6
- Forks: 52
- Open Issues: 1
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGES.rst
- License: LICENSE
Awesome Lists containing this project
README
vim-pydocstring
===============
.. image:: https://github.com/heavenshell/vim-pydocstring/workflows/build/badge.svg?branch=master
:target: https://github.com/heavenshell/vim-pydocstring
.. image:: ./assets/vim-pydocstring.gif
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.
.. code::
$ make install
Note
~~~~
Activated venv needs to be deactivated before install doq.
This can be automated with vim-plug.
.. code::
Plug 'heavenshell/vim-pydocstring', { 'do': 'make install', 'for': 'python' }
If you want install doq manually, you can install from PyPi.
.. code::
$ python3 -m venv ./venv
$ ./venv/bin/pip3 install doq
Then set installed `doq `_ path:
.. code::
$ 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``
.. code::
autocmd FileType python setlocal tabstop=4 shiftwidth=4 smarttab expandtab
Or:
.. code::
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`.
.. code::
nmap (pydocstring)
Or, if you want disable default keymapping, you can set like following.
.. code::
let g:pydocstring_enable_mapping = 0
Formatter
---------
You can set built-in formatter(Sphinx, Numpy, Google).
.. code::
let g:pydocstring_formatter = 'numpy'
Custom template
---------------
You can set custom template. See `example `_.
.. code::
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.
.. code::
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.
.. code::
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.