来自VScode的sphinx和autodocstring和python代码

Question

我正在与一个使用vscode的人合作一个项目。我们编写Python代码。 我要求他们为它们的功能生成文档字符串，然后他们使用了vscode中的自动文档字符串。这是他们想出的一个文档字符串：

"""
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
"""

应该是Google样式的文档字符串。

当我用Sphinx生成html文档时，这里提示：

虽然我应该得到类似的东西：

我在狮身人面像配置中缺少选项吗？还是自动文档字符串损坏了？

Answer 1

您显示的语法不是Google样式的语法（有关详细示例，请参见here）。它应显示为：

"""
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
"""

VSCode的autoDocstring扩展名必须正确配置以生成Google样式的文档字符串（查找autoDocstring.docstringFormat）。

Answer 2

<块引用>

我是否缺少 sphinx 配置中的一个选项？

如果您想使用 sphinx，您需要在 settings.json 中添加以下代码。

{
    "autoDocstring.docstringFormat": "sphinx"
}

转到 VS Code 菜单：

• 在 Windows/Linux 上 - 文件 > 首选项 > 设置
• 在 macOS 上 - 代码 > 首选项 > 设置

或者，文件位于（默认为 VS Code）：

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

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