在 Python 中记录 class 级变量

Question

我正在尝试记录一个 Python class，它有一些 class 级别的成员变量，但我无法使用 reST/Sphinx 对其进行适当的记录。

代码是这样的：

class OSM:
    """Some blah and examples"""
    url = 'http://overpass-api.de/api/interpreter'  # URL of the Overpass API
    sleep_time = 10  # pause between successive queries when assembling OSM dataset

但是我得到了这个输出（见绿色圆圈区域，我想在那里有一些描述两个变量的文本，如上所述）。

对于模糊不清，我深表歉意，但部分示例有些敏感

Answer 1

您有多个选项来记录 class 级变量。

将以#:开头的注释放在变量前，或放在同一行。（仅使用自动文档。）

也许是最简单的选择。如果需要，您可以使用 :annotation: 选项自定义值。如果你想类型提示值使用 #: type:.
在变量后面放一个文档字符串。

如果变量需要大量文档，则很有用。

For module data members and class attributes, documentation can either be put into a comment with special formatting (using a #: to start the comment instead of just #), or in a docstring after the definition. Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line. The latter form is restricted to one line only.
在 class 文档字符串中记录变量。（使用 sphinx-napoleon 扩展，shown in the example。）

这有一个缺点，即变量的值将被忽略。因为它是一个 class 级别的变量，所以如果您不在变量前加上 cls. 或 class_name.，您的 IDE 的静态类型检查器可能会报错。然而，这种区别很方便，因为实例变量也可以记录在 class 文档字符串中。

以下示例显示了所有三个选项。 .rst 具有额外的复杂性来说明所需的 autodoc 功能。所有情况下都包含类型提示，但也可以省略。

class OSM:
    """Some blah and examples"""

    #: str: URL of the Overpass API.
    url = 'http://overpass-api.de/api/interpreter'
    #: int: pause between successive queries when assembling OSM dataset.
    sleep_time = 10


class OSM2:
    """Some blah and examples.

    Attributes:
        cls.url (str): URL of the Overpass API.
    """

    url = 'http://overpass-api.de/api/interpreter'

    sleep_time = 10
    """str: Docstring of sleep_time after the variable."""

对应.rst

OSM module
==========

.. automodule:: OSM_module
    :members:
    :exclude-members: OSM2

    .. autoclass:: OSM2
        :no-undoc-members:
        :exclude-members: sleep_time

        .. autoattribute:: sleep_time
            :annotation: = "If you want to specify a different value from the source code."

结果：

Answer 2

如果您愿意抑制愚蠢的 linter 规则，这也有效。

class OSM2:
    sleep_time = 10;  """str: Inline docstring of sleep_time after the variable."""

在 Python 中记录 class 级变量

Documenting class-level variables in Python

restructuredtext

docstring

python-sphinx

autodoc

sphinx-napoleon