pixelneo/vim-python-docstring

A Vim plugin for generating python docstrings.

vim-python-docstring

This is a plugin to Vim and NeoVim for the creation of Python docstrings.

What it does

Docstrings for methods will contain a list of parameters and their type hints, list of raised exceptions and whether the method yields or raises.

Class docstring will have a list of atributes.

It uses Python's ast library for parsing code. This makes it quite robust solution, which can handle function signature such as

def foo(a='foo(c,d)',
    b,
    z):
        pass

Installation

If you use for example Vundle, add Plugin 'pixelneo/vim-python-docstring' to your .vimrc file.

Alternatively if you have Vim 8 and newer, you can clone this repository into ~/.vim/pack/<whatever>/start/ where <whatever> is whatever you want it to be.

If you have neovim, install python provider first: pip3 install pynvim.

Usage

The plugin has only commands which you can map however you like (i use <leader>ss for :Docstring).

1. Place cursor at the first line of the object (def ... of class ...) for which you want to create a docstring
2. Then type :Docstring or different command

The plugin uses these commands:

Command	Description
Docstring	Create full docstring
DocstringTypes	Just like :Docstring but includes type hints
DocstringLine	Create empty one-line docstring

Options:

There are things you can set.

The g:vpd_indent option

String which you use to indent your code.

Default: ' ' (4 spaces).

let g:vpd_indent = '    '

The g:python_style option

Which docstring style you wish to use.

Default: 'google'

Possible values = ['google', 'numpy', 'rest', 'epytext']

let g:python_style = 'google'

Development

Pull requests are welcome as are feature request and issue reports.

You can encounter some situations in which the plugin may not work as expected. Most notably there may be issues if your keyword for refering to instance is not self -- in such case it may be added to the list of arguments.

There are more unsolved issues.

vim-python-docstring's Issues

Vim 32 bits and Python 64 bit.

I have this problem:

May it be due to that I have Vim32 and Python (Anaconda) 64 bits?

Unfortunately I have to cope with this setup since Vim64 does not seem to be well supported and at the same time I gotta work with the 64 bits of Anaconda.

Any workaround?

g:python_style in vimrc file is ignored

I found that even if I setup let g:python_stype="numpy" in the .vimrc file. It still uses google style.

My guess is because of the following lines:

vim-python-docstring/python/vimenv.py

Lines 62 to 64 in 60f58e3

	settings = {'g:python_indent': ' ', 'g:python_style': 'google'}
	for k, v in settings.items():
	vim.command("let {} = get(g:,'{}', \"{}\")".format(k, v, v))

Support type hints

Add support for type hints in function arguments.
e.g.

def foo(a:str, b:int):
    pass

should get this docstring:

def foo(a:str, b:int):
    """
    Args:
        a (str): ...
        b (int): ...
    """
    pass

This can be done using typing.get_type_hints('foo'). Or in case foo is in class A, typing.get_type_hints('A.foo') (this needs to be distinguished – using ast).

f-string parameter to error message included among raised errors

With this function (reproduced with only this contents in a file too):

def f(x, y):
    if x == 1:
        raise ValueError(f'x ({x}) == 1')

    return a, b

Calling :Docstring produces this docstring:

     """

    Args:
        x:
        y:

    Returns:
        

    Raises:
        ValueError:    x:
    """

Expected output:

     """

    Args:
        x:
        y:

    Returns:
        

    Raises:
        ValueError:
    """

It seems related to the f-string.

I'm on Ubuntu 20.04, and my output of vim --version is:
vim_version.txt

One minor README typo I didn't feel was worth a separate issue: Instalation -> Installation

Support async functions

Plugin does not work for functions starting with async.
e.g.

async def foo(a, b):
    pass

style ignored in lunarvim

Numpy style is ignored in lunarvim with the following config

   {
    'pixelneo/vim-python-docstring',
    config = function()
      vim.cmd("let g:python_style = 'numpy'")
    end,
  },

Related to #1

[Feature Request] remove the indent before the parameters in Numpy style

The docstring generated by the plugin.

"""

Parameters
----------
    foo1 :
    foo2 :
    ...

"""

Expected result

"""

Parameters
----------
foo1 :
foo2 :
...

"""

Is it possible to add an option for the user to choose? Or just change the default format.

E492: Not an editor command

As it is mentioned in README.md I added :

Plugin pixelneo/vim-python-docstring

to my .vimrc file.

When I want to use it by doing

:Docstring

however I get the error:

E492: Not an editor command

I would appreciate any comment.

Function without body

If function does not have a body, plugin does not work.
e.g.

def foo(a,b):

Improve code quality

Code quality is not great, lot of don't touch if it works vibes

Attributes are not in order

Dear developer,

First of all thanks for the great plugin!

The attributes in the docstring don't seem to contain any order. Is it possible to set it such that it retains the original order they appear in the definition of the function?

Thank you!

No type for docstring

Maybe I am missing something, but how can I add type along with param?

Example:

def foo(foo_one, foo_two):
    """Function with reStructuredText style docstring

    :param foo_one:
    :type foo_one:
    :param foo_two:
    :type foo_two:
    """
    pass

Include default values

Include the default values in the doc string in cases such as :

def foo(a: int = 3, name: str = 'bar'):
     pass

Doctring ERROR: module 'ast' has no attribute 'unparse'

Hi,
after some environment changes (which I am unable to track down) I am not getting this error when using :Docstring in vim.

Doctring ERROR: module 'ast' has no attribute 'unparse'

Do you have any suggestion on how to debug this?
I've tried opening python and calling ast.unparse but that does not give me an error.

Missing colons in list of class Attributes

Hi there, thanks for this amazing plugin!

Just wanted to let you know that when I generate a class docstring,
I see a list of attributes which are missing the colons at the end of the attribute names.
E.g.:

class PointsToRaster:
"""

Attributes:
    x_raster
    x_dim_da

"""

Use of Type Hinting

Add parameter/return types when users include type hint in their code

Function without trailing empty line

If a function is the last thing in a file and its body does not have an empty line after it, the plugin does not work.
e.g.

# ... there can be some code at the beginning

def foo(a,b):
    pass

(there is no empty line at the end)

Update existing docstring

Why: Now, a new docstring is always created. On a change of some arguments, on function that already has some docstring, that docstring should only be updated – new args added, old ones removed.

Improve error handling

Hello,

Nice plugin by the way.

I've made some small error handling improvements to your plugin on my own machine that I would like to raise a PR for.

I've just improved how errors are logged mainly (no stack traces, just concise error messages).

If you happy with this I can raise a PR with your approval.

Cheers!

Add `Returns: None` when no explicit return statement is found

Hi, just another small feedback on your great plugin.

I haven't found any official guideline for what to put in a docstring when no explicit return statement is found,
but this stackoverflow question suggests it should be like this:

"""Prints the element given as input

Args:
    x: any element
Returns:
    None
"""

Do you think this is something you could/would like to implement?

Function without parameters

With the following code, the plugin gives Docstring ERROR: list index out of range:

def f():
    pass

Add support for functions that enforce keyword-only arguments.

Currently the docstring plugin produces unexpected results when used on a function that enforces keyword-only arguments. For example:

def foo(*, arg1, arg2):
    return arg1 + arg2

produces an empty docstring when using the plugin and the result is:

def foo(*, arg1, arg2):
    """

    Returns
    -------
        

    """
    return arg1 + arg2

It would be nice if the * indicating keyword-only args would be supported.