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: 4 days 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 13 years ago)
• Default Branch: master
• Last Pushed: 2023-07-15T10:11:43.000Z (over 1 year ago)
• Last Synced: 2025-01-11T17:49:45.674Z (12 days ago)
• Topics: docstring, python, vim
• Language: Vim Script
• Homepage:
• Size: 9.24 MB
• Stars: 337
• Watchers: 7
• 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.