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

Question

VS Code 如何在鼠标悬停时解释 Python docstrings 中的标记/Markdown 和布局？

有几个问题报告了这种显示方式，但似乎并没有任何官方信息说明当前的格式是什么。

- AdSR

---

这是 GitHub 上的一个问题链接（https://github.com/Microsoft/vscode-python/issues/38），自从3年前开启以来似乎没有得到很好的解决进展。问题似乎被搁置了一段时间。如果需要在 IDE 中进行良好的 Docstring 渲染，则可能需要考虑使用 PyCharm。 - Abel Cheung

又过了两年，这个问题仍然存在（使用标准docstrings）：https://dev59.com/9ZWIqIgBuLDinofp_Hhb - D.L

Answer 1

VS Code在鼠标悬停时可以良好地呈现Markdown，但无法很好地呈现标准的文档字符串格式

VS Code Python扩展将使用您放入文档字符串中的Markdown来作为智能提示鼠标悬停信息，但这并不符合Python常用的任何公认/使用的文档字符串格式。它不能正确地布局任何这些常见格式（截至2020年5月）。

更新（2023年4月）：Sphinx已经更新以支持在其自动代码生成中在文档字符串中使用Markdown，这意味着您可以在Markdown中放置所有文档字符串，并且它们将在VS Code悬停中显示良好，并且同时与Sphinx一起使用

因此，您有以下选项：

1. 坚持使用适用于现有Python文档工具和实用程序（如Sphinx）的主要格式
2. 在您的文档字符串中使用Markdown，在VS Code中呈现良好，但与大多数其他文档工具不兼容

---

更多细节/示例

Python文档字符串的前三种格式为：

• Google
• Sphinx
• 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。

此外，请注意主要函数定义中的类型提示（例如a：str中的str）对于args和返回类型提示很好地呈现（甚至带颜色），但对于kwargs（例如没有类型提示的b=5）则不显示。

- LightCC

---

这让我很困扰，谢谢分享！我无法正确地进行格式化，结果发现我只需要切换到PyCharm即可 ;) - JarroVGIT

目前来看，我会说PyCharm在Python方面比Code更具优势。可惜它不能像处理Python一样处理其他100种语言... :) - LightCC

Answer 2

据我所知，目前没有官方支持的格式。该代码运行了一些函数来将RST的某些部分转换为Markdown以便显示，但这基本上就是全部内容。

执行转换的代码可以在这里找到。测试（查看一些实际示例的好方法）可以在这里找到。

- hirolau

Answer 3

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

使用 @param_name: 参数的定义 来进行正确的文档说明。

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 Code 将显示与参数相应的 定义。也就是说，当我输入 用户名 参数时，将显示 用户的名称。这里是图片: 和另一个参数：

- Parvat . R

---

这也适用于 :param username: 用户名。 样式和 Google 风格的 Args: 列表。 - Benjamin Carlsson

Answer 4

你需要使用sphinx.ext.napoleon。当你在conf.py中激活它时，你的普通Google或带类型的docstrings将被转换为reStructured文本，然后输入Sphinx。结果是漂亮的文档和漂亮的（而且易于编写！）docstrings。该扩展程序已经成为Sphinx发行版的一部分，截至2022年4月。

- Bob Denny

---

这是否修复了VS Code显示对象工具提示的方式？ - LightCC

你说的“修复”是什么意思？Napoleon允许将Google风格的文档字符串导入到Sphinx中，并生成漂亮的文档。如果你喜欢那种格式用于工具提示的话，可以这样做。 - Bob Denny

这个问题涉及到在使用函数时，当你把鼠标悬停在它上面时，VS Code的智能感知预览功能中显示函数文档字符串的工具提示。这个答案似乎只关注Sphinx和单独的文档。VS Code不能很好地呈现普通的Python文档字符串格式。 - LightCC