来自 VScode 的 sphinx 和 autodocstring 与 python 代码答案

【问题标题】：sphinx and autodocstring from VScode with python code来自 VScode 的 sphinx 和 autodocstring 与 python 代码
【发布时间】：2018-07-30 09:47:43
【问题描述】：

我正在与使用 vscode 的人合作开展一个项目。我们编写 Python 代码。我让他们为他们的函数生成文档字符串，他们使用了来自 vscode 的 Autodocstring。这是他们提出的一个文档字符串：

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

它应该是谷歌风格的文档字符串。

当我使用 Sphinx 生成 html 文档时，我得到了以下信息：

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

我是否缺少 sphinx 配置中的选项？还是 Autodocstring 坏了？

【问题讨论】：

标签： python visual-studio-code docstring

【解决方案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）。

【讨论】：

Args 是Arguments 的别名，所以这应该不是问题。但是，您的参数类型在 花括号 后跟一些连字符 (file_path {str} --)，当（如前面的答案）它应该在以冒号结尾的括号中 (file_path (str):) .

【解决方案2】：

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

如果你想使用sphinx你需要在settings.json中添加下面的代码。

{
    "autoDocstring.docstringFormat": "sphinx"
}

转到 VS Code 菜单：

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

或者，文件位于（默认情况下 VS Code）这里：

视窗%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

【讨论】：