Visual Studio Code 支持的 Python 文档字符串格式是什么？

Question

VS Code 如何在鼠标悬停时解释 Python 文档字符串中的标记/降价和布局？

此显示报告了几个问题，但似乎不存在关于当前格式的任何官方信息。

原文由 AdSR 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

VS Code 在鼠标悬停时可以很好地呈现降价 - 但不能很好地呈现标准文档字符串格式

VS Code Python 扩展将使用您放入文档字符串中的 markdown 以获取智能感知鼠标悬停信息，但这并不真正符合 Python 的任何普遍接受/使用的文档字符串格式。它没有正确布局任何这些常见格式（截至 2020 年 5 月）。

所以，你的选择是：

1. 坚持使用一种可以与现有 Python 文档工具和实用程序（如 Sphinx ）一起使用的主要格式
2. 在文档字符串中使用 markdown，在 VS Code 中看起来不错，但与大多数其他文档工具不兼容

---

更多详细信息/示例

前 3 名 Python 文档字符串格式是：

• 谷歌
• 狮身人面像
• NumPY/休息

VS Code 将采用 ReST 格式（NumPY 样式）并正确布局每个部分的标题（每个项目下面都有破折号），但在所有格式中，部分内容都未格式化并与所有换行符一起被删除。

如果您直接在文档字符串中使用 markdown，它是受支持的，但是您不满足文档字符串对 Sphinx 等自动文档框架的格式要求。例如，我从这里开始使用 Sphinx 格式，然后使用 VS Code 的降价工具提示对其进行修改以使其看起来更好

def autodoc_test_numpy(self, a: str, b: int = 5, c: Tuple[int, int] = (1, 2)) -> Any:
    """[summary]

    ### Parameters
    1. a : str
        - [description]
    2. *b : int, (default 5)
        - [description]
    3. *c : Tuple[int, int], (default (1, 2))
        - [description]

    ### Returns
    - Any
        - [description]

    Raises
    ------
    - ValueError
        - [description]
    """

会像这样渲染：

请注意，这里最后的“Raises”部分有带破折号的下划线，使其成为 1 级标题（这是 ReST 样式）。看看它有多大！我通过在文本前面使用 ### 而不是在下一行用连字符下划线，将另一个降低到 h3 。

另外，请注意主函数定义中的 类型提示（如 str 中的 a: str ）为 args 和返回类型提示呈现良好（甚至着色），但未显示kwargs（例如 b=5 没有类型提示）。

原文由 LightCC 发布，翻译遵循 CC BY-SA 4.0 许可协议