nilsjpwerner / autodocstring

VSCode extension that generates docstrings for python files

NilsJPWerner

My personal website

autodocstring's Issues

Numpy and Sphinx

Hello Nils,

Thanks for the package, it's great! I was wondering whether you have a timeline for a minimal Numpy and Sphinx integration?

Still attempts to make a docstring when not in function & when already exists

It doesn't realise that this is not in a function:

And this one it doesn't realise it already has a docstring.

Pycharm usage

Hi,

I love this extension and have been using it heavily

Is there any way that it can be ported to Pycharm. I can help anyone if some one can point me to what all things should be done to enable this

Thnaks
Ravi

Using US international keyboard with dead keys using 3 single quotes results in infinite insertion

To enter umlauts US international keyboard doesn't print " immediately, but rather waits for the next character (e.g. "o will from ö).

Please upload to the VSCode extension marketplace.

Great work. I believe this is a very useful extension to VSCode. It works great in my machine.

Can you upload it to VSCode extension marketplace? so that more people can find and use it.

will plan to support generate arguments with **kwargs and *args?

async def function autoDocstring invalid

async def fun(a, b=1):
"""[summary]
"""
if not a:
raise KeyError
return a + b

my setting：
"autoDocstring.docstringFormat": "google"

Python3.6 Type annotations not supported

Type annotations in the form of

def foo(bar: str)
    """A method with type annotation
    
    Args:
        bar (str): a very descriptive parameter
    """

are not treated as information about type (and maybe even automatically filled in the args section of the docstring like seen above), but rather as part of the variable name when generating the docstring. This leads to undesired behaviour when creating docstrings of functions or methods that have these annotations, as can be seen below.

def foo(bar: str)
    """A method with type annotation
    
    Args:
        bar: str ([type]): a very descriptive parameter
    """

Methods on Classes

Have a time preview for make work in methods inside classes?
Great job!!

Remove trailing whitespace from empty newlines for pylint compliance

It'd be great if the empty newlines generated by autoDocstring didn't contain trailing whitespaces. I'm getting tired of pressing backspace to delete them to make pylint happy.

Feature Request: Dense sphinx parameters

I typically use the dense version of parameter definition for my docstrings (as documented here)

For example I will have the following docstring...

def make_config(name, var_dict, title=None, description=None, **kwargs):
    """ Creates a config instance from scratch.

    :param str name: The name of the config
    :param dict var_dict: The dictionary of config variable definitions
    :param str title: The title of the config, defaults to None, optional
    :param str description: The description of the config, defaults to None, optional
    :return: A new config class
    :rtype: class
    """

rather than the long version (which includes type lines)...

def make_config(name, var_dict, title=None, description=None, **kwargs):
    """ Creates a config instance from scratch.

    :param name: The name of the config
    :type name: str
    :param var_dict: The dictionary of config variable definitions
    :type var_dict: dict
    :param title: The title of the config, defaults to None, optional
    :type title: str
    :param description: The description of the config, defaults to None, optional
    :type description: str
    :return: A new config class
    :rtype: class
    """

Every time autoDocstring generates a docstring I have to manually re-edit the docstring to remove :type {variable}: {type} and add the type as a prefix to the :param.

It would be nice if autoDocstring either had a checkbox toggle or a variant on the Sphinx docstring that would save me some time rewriting the generated docstring.

Arguments in new lines are ignored

def example(
  a,
  b=None,
  c=2,
  d="hello",
):
  """[summary]
  """

  pass

Cannot read property 'document' of undefined

Windows 10 vscode 1.27.2

 ERR Cannot read property 'document' of undefined: TypeError: Cannot read property 'document' of undefined
	at activateOnEnter (C:\Users\almenon\.vscode\extensions\njpwerner.autodocstring-0.2.3\out\src\extension.js:19:36)
	at context.subscriptions.push.vs.workspace.onDidChangeTextDocument.changeEvent (C:\Users\almenon\.vscode\extensions\njpwerner.autodocstring-0.2.3\out\src\extension.js:13:90)
	at e.fire (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:99:917)
	at e.$acceptModelChanged (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:742:362)
	at e._doInvokeHandler (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:681:309)
	at e._invokeHandler (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:681:27)
	at e._receiveRequest (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:679:802)
	at e._receiveOneMessage (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:678:993)
	at c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:677:791
	at c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:98:597
	at e.fire (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:99:917)
	at a (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:164:787)
	at Socket.n._socketDataListener (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:164:1006)
	at emitOne (events.js:116:13)
	at Socket.emit (events.js:211:7)
	at addChunk (_stream_readable.js:263:12)
	at readableAddChunk (_stream_readable.js:250:11)
	at Socket.Readable.push (_stream_readable.js:208:10)
	at Pipe.onread (net.js:594:20)

How to use ''' instead of """ ?

Hello, I intend to use ' over " , but I don't know how to do .
Support both would be better,

Numpydoc docstring: last line in docstring should be empty and first line after docstring shold be code

Hi, first of all, thanks for the useful VS Code extension.

I mainly use the Numpy docstring conventions, and after a first glance, I found the extension do not fully follow the Numpydoc conventions with respect to that the last line in docstring should be empty and the first line after docstring should be code.

Hence, the following example:

def fun(a, b=1):
    """
    c = 1
    d = 'hello'
    return c, d

shold result in:

def fun(a, b=1):
    """
    [summary]

    [description]

    Parameters
    ----------
    a : [type]
        [description]
    b : int, optional
        [description] (the default is 1, which [default_description])

    Returns
    -------
    [type]
        [description]

    """
    c = 1
    d = 'hello'
    return c, d

but the extension outputs:

def fun(a, b=1):
    """
    [summary]
    
    [description]
    
    Parameters
    ----------
    a : [type]
        [description]
    b : int, optional
        [description] (the default is 1, which [default_description])
    
    Returns
    -------
    [type]
        [description]
    """

    c = 1
    d = 'hello'
    return c, d

docstring contain newline with black

can we remove these blanks?

numpy format generates 'Parameters' keyword with a colon

numpy format generates 'Parameters' keyword with a colon, but numpy document specifies it without the colon:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard

Omit 'returns' for functions annotated -> None

For functions and methods without return value, the 'returns' section in the docstring is unnecessary. autoDocstring gets confused when the function is annotated with None as return type, as shows:

def inferred_void(value):
    """[summary]
    
    Args:
        value ([type]): [description]
    """

    print(value)


def annotated_void(value: str) -> None:
    """[summary]
    
    Args:
        value (str): [description]
    
    Returns:
        None: [description]
    """

    print(value)

(using Google style docstrings)

Support for PEP 484

Implementing PEP 484 would let the extension parse function-annotations to automatically fill in types.

For example, the generated doc-string for this annotated function is currently:

def foo(bar: str) -> str:
	"""[summary]
	
	Arguments:
		bar: str {[type]} -- [description]
	
	Returns:
		[type] -- [description]
	"""

	return bar

When it could have generated:

def foo(bar: str) -> str:
	"""[summary]
	
	Arguments:
		bar {str} -- [description]
	
	Returns:
		str -- [description]
	"""

	return bar

`customTemplatePath` configuration does not substitute VSCode variables

In settings.json I have:

"autoDocstring.customTemplatePath": "${workspaceFolder}/.vscode/pydocstring_template",

When I try to generate docstrings I get:

AutoDocstring Error: Template could not be found: ${workspaceFolder}/.vscode/pydocstring_template

It works with:

"autoDocstring.customTemplatePath": "/Users/savo/Documents/Projects/something/something/.vscode/pydocstring_template",

I have my other configurations using this same variable with no issues, for example:

...
"python.linting.mypyEnabled": true,
"python.linting.mypyArgs": [
    "--config-file", "${workspaceFolder}/src/mypy.ini"
],
...

Not sure if this is an extension bug but since other configurations work with the same variable I assumed it is. Let me know if any other info is necessary.

How to change the formatting of Visual Studio Codes docstring preview?

How would one go about making Visual Studio Code recognize e.g. the Google docstring format in its docstring ""preview on hover" functionality?

Google searching has left my question unanswered.

flake8 W293:blank line contains whitespace

Not working with async def

Only generate summary when using async def.
For example:
async def some_func(some_kwarg): """[summary] """

BTW. Great extension!

Generation errors in creating docstring

Issues:

• Doesn't detect that it hasn't been indented
• Doesn't auto-detect type hinted types (thinks they are part of the name)
• Doesn't detect the return (^[1] does)
• Argument {f} doesn't appear in keyword arguments
• **kwargs isn't recognised as a keyword argument

Feedback:

• Note that *args is a list (auto-detection) and **kwargs is a dict . Anything that starts with *, or ** does this too.

^[1]:

Which key could be used to navigate through each input field highlighted?

Hi, this plugin is very cool, but in your demonstration GIF, the cursor first stops at [summary], and then the content you input replaced [summary], and then the cursor just jumped to the next input field [type]. However, I tried 'enter' or 'tab' on my code, it just keeps editing [summary] and I could not jump to the next input field.

I'm using macOS 10.13.4, VSCode 1.22.2. I wonder which key or key combination I should use to navigate through each input field that this plugin highlighted?

Thank you very much.

generate arguments add a blank line

last picture is auto generate.

last picture ,i change something ,add blank line .be more beautiful

Support for PEP 526

With the addition of support for PEP 484 (#22, #23), support for PEP 526 would also be very desirable.
This would have to take into consideration substitutions for typing's type declarations.

For example:

from typing import (List,)

def foo(bar: List[str]) -> str:
	"""[summary]
	
	Arguments:
		bar {list(str)} -- [description]
	
	Returns:
		str -- [description]
	"""

	return bar[0]

Custom docstring

feature request

Consider adding a feature to create custom docstring formats that can be used as user settings. It would be quite useful when there is need to maintain a specific coding style across a project.

Numpy docstring with multiple returns

Hi,

As an extension of my issue #61, I also think it would be nice if the Numpy docstring factory numpy.ts would process multiple return values.

Hence, the following example:

def fun(a, b=1):
    """
    c = 1
    d = 'hello'
    return c, d

shold result in:

def fun(a, b=1):
    """
    [summary]

    [description]

    Parameters
    ----------
    a : [type]
        [description]
    b : int, optional
        [description] (the default is 1, which [default_description])

    Returns
    -------
    c : [type]
        [description]
    d: [type]
        [description]

    """
    c = 1
    d = 'hello'
    return c, d

but the extension currently outputs:

def fun(a, b=1):
    """
    [summary]
    
    [description]
    
    Parameters
    ----------
    a : [type]
        [description]
    b : int, optional
        [description] (the default is 1, which [default_description])
    
    Returns
    -------
    [type]
        [description]
    """

    c = 1
    d = 'hello'
    return c, d

Class Docstring

Feature Request:

Is it possible to make the docstring show something different for a Class? For example, I use numpy docstring system and they have a slightly different format for class docstrings, the addition of an attributes section being the most notable.

For numpy, only public attributes should be listed, so maybe it could go through all the attributes and parse for ones without a leading _?

Docstrings conflict with Pylint C0303: Trailing Whitespace

The newlines which are pasted by the docstring-extension are indented and thereby cause an warning when using pylint with the C0303 message enabled.

How to jump to next selected location and edit like in the screenshot?

In the screenshot after editing [summary] we can directly go to edit [type]. What's the key shortcut for this? This may be a naive question but I really cannot find out how to do it...

This extension is consuming more than 200MB [serious issue]

I think there might be an error in your deployment, because when I install this extension, I found out that its test code are also included, you can find it at the following directory:

~/.vscode/extensions/njpwerner.autodocstring-0.2.0/.vscode-test

This folder is taking 280MB in my laptop.
Therefore you should exclude it on the next deployment.

Erases previously existing docstring if editing first line

When I'm editing a docstring that has already been filled out, and hit Enter when at the first line of the docstring, it erases all of the docstring and replaces it with the docstring template.

I can fix it with a quick Ctrl + z, but it really shouldn't happen in the first place.

In my mind, it should really just create a new docstring template rather than erasing the old one, but I'm not familiar with how the extension works, so that might not be feasible/desirable.

Failing to generate docstring for multiline function definitions

When using the plugin on a function definition spanning multiple lines, it fails, and creates and empty docstring, as shown in the image below.

On a side note: the text is wrong in the single line function definition, but I choose to ignore that, as I assume that issue is being worked on?

P.S. Great extension, thanks!

Edit: Fix typo in screenshot

Unecessary trailling spaces

autoDocstring adds trailling spaces on blank line 3 of the following example, and more generally on blank lines between sections.

1  def function():
2     """[summary]
3     
4     [description]
5     """
6     pass

They should be removed in order to be compliant with PEP8.

Option to turn off type generation entirely

Hi there, great extension! I'm wondering if you'd be willing to add an option which completely disables the generation of type information inside the generated docstrings. I only have experience with sphinx, so I'm not sure how the other docstring types would look, but since my code is using type annotations I tend to write my docstrings like this:

def foo(some_param: str) -> int:
    """Some function.
    
    :param some_param: the thing that does the other thing
    :return: some meaning of life or whatever
    """
    return 42

(omitting the types entirely, since it's possible to generate the sphinx docs using a plugin such as https://pypi.org/project/sphinx-autodoc-annotation/ or https://github.com/agronholm/sphinx-autodoc-typehints).

Happy to help with a PR if you're ok with the idea (although, I'd probably need to research if the other docstring types work without type information).

Type hinting with default value ignores variable name

def example(a: int = 1) -> int:
  """[summary]
  
  Keyword Arguments:
    int {[type]} -- [description] (default: {1})
  
  Returns:
    [type] -- [description]
  """

  return a + 1

not have "return‘’

Hello auth:
def test1(msg): |index1 return msg def test2(msg): |index2 return msg
when I use "ctrl+shift+2" in index1，I can't see return
but I use "ctrl+shift+2" in index2，I can see return
It is not comfortable
I can't speak English,sorry!

pre-fill method name in front of summary

Hi there,

thanks for great plugin. Obviously I start method docstring with method name. Would it be possible to have the option to pre-fill the method name in front of summary?
I would also think about some templating system which allows customizing the auto-generated docstrings.

Example of my docstring:

 def is_authorized(self, ticket_id):
        """
        is_authorized returns true for users been authorized
        to retrieve RT update.

        :param ticket_id:   int:    Ticket number.
        :return:            bool:   True for authorized user, false otherwise.
        """

Fails to create snippet when guessTypes: false and no return statement

If "autoDocstring.guessTypes" is set to false, autoDocstring fails to create a snippet for functions lacking both a return statement and annotated return type.

Example:

def explicit_return(value):
    """[summary]
    
    Args:
        value ([type]): [description]
    
    Returns:
        [type]: [description]
    """

    return print(value)

def no_return(value):
    """

    print(value)

After three quotes and Enter, no snippet is inserted in no_return.
Confirmed with all four docstring factories.

Update docstring

Hey,
I was wondering whether there was already a way to auto-update docstrings.

def start(a):
  """[summary]
  
  Arguments:
    a {[type]} -- [description]
  """
  pass

to auto update to:

def changed(a,b):
  """[summary]
  
  Arguments:
    a {[type]} -- [description]
    b {[type]} -- [description]
  """
  pass

keeping the values of the already existing data lines.

And if some argument disappears, keep track of it in "Deleted" for example:

def deleted(b):
  """[summary]
  
  Arguments:
    b {[type]} -- [description]

  Deleted:
    a {[type]} -- [description]
  """
  pass

Docstring can be generated at end of tripe quotes

If I make a function:

def foo(bar):
    """[summary]
    
    Arguments:
        bar {[type]} -- [description]
    """

And I hit enter after the last tripe quotes, this happens:

def foo(bar):
    """[summary]
    
    Arguments:
        bar {[type]} -- [description]
    """[summary]
    """

Check for this please!
This could be fixed by just checking that there is no docstring anywhere else in the function, would also prevent the issue of second triple quotes doing this too.

Docstring will not generate when triple quote string exists in function body

This only happens when the quote style is the same as the triple quote string inside the function body. Also happens with non-f-strings.

See example:

def foo(bar):
    # Try to add a docstring here (if your quote style is also """)
    x = """hello"""
    return x

Parameters with empty string as default are ignored

def example(a,b=None,c=2,d="",e="hello"):
  """[summary]
  
  Arguments:
    a {[type]} -- [description]
  
  Keyword Arguments:
    b {[type]} -- [description] (default: {None})
    c {[type]} -- [description] (default: {2})
    e {[type]} -- [description] (default: {"hello"})
  """

  pass

d is missing completly.

unit_test script does not work on Windows

Seems to be caused by the single quotes around the mocha glob.

Add option for `[summary]` to be on a new line

Please add an option on the settings to make the [summary] line be on a new line after the quotes.
Thanks ahead

"""
[summary]

...
"""

Docstring generation is not sensitive to location in file

When I type a triple-quote """ and then press enter anywhere in the file, the following docstring template is generated.

"""[summary]
"""

The template should only be generated if the triple quotes are typed below a function.

Using `Shift + Windows + 2` impossible

On Windows 10.

Hitting Shift + Windows + 2 opens the items on my taskbar, and VSCode knows nothing about it.

Please add either an option to configure the keyboard shortcut (preferable) or set it to something else like Ctrl + Alt + 2

Semicolon ":" appearing after "Parameters" and no blank line exists before "Raises" in NumPy format

Hi there,

Let me start by saying that you've done a great job with this package! The amount of time I have saved on documentation since I started using it is unreal. 👍

Having said that, I think there might be a small bug which causes a semicolon to be printed after "Parameters", under numpy format. Here is an example generated docstring:

@ndim.setter
    def ndim(self, ndim):
        """[summary]
        
        Parameters:
        ----------
        ndim : {[type]}
            [description]
        Raises
        ------
        TypeError
            [description]
        ValueError
            [description]
        
        """
        ......

Also it seems that the isn't a blank line between the "Parameters" and "Raises" sections.

Obviously, these are not big issues, but I thought I'd mention them in case they're easy to polish out.