Python 代码中注释和文档字符串的基本语法

Question

我正在学习如何使用 Sphinx 为我的代码创建文档。在我看到一些这样的例子之后：

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

评论中使用什么语言来让 Sphinx 理解并捕捉它们？没有这种语法和逻辑，Sphinx 就看不到我的代码中的注释，当我生成 HTML 时，模块是空的。

举个例子：

Answer 1

您必须区分 comments 和 docstrings（完整称为“文档字符串”）。

参见 PEP8 and notice docstrings apply only to 模块、函数、类和方法。对于提到的对象，您可以应用 your_object.__doc__ 以编程方式检索文档字符串；变量没有 docstrings.

关于你的例子：

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """

Sphinx 将检索的文档字符串中可以使用 3 种流行的语法：

reST 是基本语法。
Numpy 风格的文档字符串。
Google 风格的文档字符串。

标准是在 Numpy 或 Google 风格 之间进行选择（目前它们提供更好的可读性和功能，以及风格指南）。要使这些工作正常，您需要使用 Sphinx-Napoleon extension，请查看官方文档中的概述。

Python 代码中注释和文档字符串的基本语法

Basic Syntax of comments and docstrings in Python code

docstring

python-sphinx

sphinx-napoleon