CODEWITHSUNDEEP
pythonvisual-studio-codedocstring
JPFrancoia
JPFrancoia

Reputation: 5629

sphinx and autodocstring from VScode with python code

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:

enter image description here

While I should get something like that:

enter image description here

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

Upvotes: 4

Views: 17626

Answers (2)

Milovan Tomašević
Milovan Tomašević

Reputation: 8673

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

enter image description here

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

Upvotes: 4

charlie80
charlie80

Reputation: 836

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).

Upvotes: 4

Related Questions