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文档字符串格式为：

• Google
• 狮身人面像
• 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]
    """

将这样渲染：

请注意，这里的最后一个“提高”部分带有带下划线的下划线，使其成为1级标头（这是ReST样式）。看看有多大！我将另一只撞到h3。

此外，请注意，主函数定义中的type hints（如str中的a: str）对于args和返回类型提示呈现良好（甚至彩色），但不是显示为kwarg（例如，没有类型提示的b=5）。

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。这是一张图片： 和另一个参数：