Visual Studio Code 支持的 Python 文档字符串格式是什么? [英] What is the Python docstring format supported by Visual Studio Code?

问题描述

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

How does VS Code interpret markup/markdown and layout in Python docstrings on mouse hover?

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

There are several issues reported for this display but there doesn't seem to exist any official info on what the current format is.

推荐答案

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

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

VS Code renders markdown fine in mouse hovers - but doesn't render standard docstring formats well

The VS Code Python extension will use markdown that you put into a docstring for intellisense mouse hover information, but this doesn't really meet any of the commonly accepted/used docstring formats for Python. It doesn't properly layout any of those common formats (as of May 2020).

所以，您的选择是:

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

---

更多细节/示例

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

---

More Details / Example

The top 3 Python docstring formats are:

• 谷歌
• 狮身人面像
• NumPY/ReST

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

VS Code will take ReST format (NumPY style) and properly layout the headers from each section (each item with the line of dashes under it), but in all the formats, the section content is unformatted and munged together with all the linebreaks dropped.

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

If you use markdown directly in the docstrings, it is supported, but then you aren't meeting the formatting requirements of docstrings for auto documentation frameworks like Sphinx. For example, I started with Sphinx format here and modified it to look better with VS Code's markdown tooltips

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.

Notice that the final "Raises" section here has the underlining with dashes that makes it a level 1 header (which is the ReST style). Look how big it is! I bumped the other down to h3 by using ### in front of the text instead of underlining it with hyphens on the next line.

另外，请注意主函数定义中的类型提示 (像 a: str 中的 str) 为 args 和返回类型提示渲染良好(甚至着色)，但不会为 kwargs 显示(例如 b=5 没有类型提示).

Also, note that the type hints in the main function definition (like str in the a: str) render well (even colored) for args and the return type hint, but are not shown for kwargs (e.g. b=5 without the type hint).

这篇关于Visual Studio Code 支持的 Python 文档字符串格式是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！