sphinx and autodocstring from VScode with python code

Question

I'm collaborating on a project with people that use vscode. We write Python code. I asked them to generate the docstrings for their functions, and they used the Autodocstring from vscode. Here is a docstring they came up with:

"""
Subclass ObjectCAD renderToFile method to render the scad file
in renders_dir

Arguments:
    file_path {str} -- the destination path for the scad file

Returns:
    None
"""

It's supposed to be a Google style docstring.

When I generate a html doc with Sphinx, here is whet I get:

While I should get something like that:

Am I missing an option in sphinx configuration? Or is the Autodocstring broken?

charlie80 · Answer 1 · 2019-02-18T22:55:38.347

4

The syntax you show is not Google-style syntax (see here for detailed examples). It should read:

"""
Subclass ObjectCAD renderToFile method to render the scad file
in renders_dir

Args:
    file_path (str): the destination path for the scad file

Returns:
    None
"""

The autoDocstring extension for VSCode must be properly configured to generate Google-style docstrings (look for autoDocstring.docstringFormat).

edited Feb 18 '19 at 22:55

answered Jan 18 '19 at 09:59

charlie80

806
1
7
17

1

`Args` is an alias for `Arguments`, so that shouldn't be an issue. However, you have your argument-type in *curly braces* followed by some hyphens (`file_path {str} --`), when (as in the earlier answer) it should be in parentheses ending with a colon (`file_path (str):`). – luskwater Dec 10 '19 at 18:31

score 1 · Answer 2 · answered Mar 23 '21 at 23:26

Am I missing an option in sphinx configuration?

If you want to use sphinx you need to add the code below in the settings.json.

{
    "autoDocstring.docstringFormat": "sphinx"
}

Go to VS Code menu:

On Windows/Linux - File > Preferences > Settings
On macOS - Code > Preferences > Settings

Or, file is located (by default VS Code) here:

Windows %APPDATA%\Code\User\settings.json
macOS $HOME/Library/Application Support/Code/User/settings.json
Linux $HOME/.config/Code/User/settings.json

Example with doctring:

def func1(arg1, arg2):
    """
    This function take two arguments, sets the first to equal the second, then returns the new first argument. Pointless.
    :param arg1: Some value
    :param arg2: Another value
    :return: arg1
    """
    arg1 = arg2
    return arg1

sphinx and autodocstring from VScode with python code

2 Answers2