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/ReST

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

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

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。

另外，请注意主函数定义中的type hints（如a: str 中的str）对于args 和返回类型提示呈现良好（甚至是彩色），但对于kwargs（例如@ 987654331@ 没有类型提示）。

Answer 2

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

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

Answer 3

好的，我找到的一种方法是：

使用@param_name: The parameter's definition 获取正确的文档。

class User:
    def __init__(self, username:str, password:str):
        """A class for a user
        @username: The name of the user.
        @password: A strong password for the user.
        """
        self.username = username
        self.password = password

VS 代码将显示definitons 对应的参数。也就是说，当我输入username 参数时，将显示The name of the user。这是一张图片： 和另一个参数：