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

Question

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

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

Answer 1

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

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

所以，你的选择是：

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

更多细节/示例

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

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

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

如果您直接在 docstrings 中使用 markdown，它是受支持的，但是您不符合自动文档框架（如 Sphinx）的 docstrings 格式要求。例如，我从这里开始使用 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没有类型提示）。

Answer 2

据我所知，没有支持的官方格式。该代码运行了一些函数，用于将 RST 的某些部分转换为要显示的 Markdown，但仅此而已。

可以在此处找到执行转换的代码。可以在此处找到测试，这是查看一些实际示例的好方法。