3

我正在尝试记录一个具有一些类级成员变量的 Python 类，但我无法使用 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

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

在此处输入图像描述

我为模糊道歉，但部分示例有些敏感

4

2 回答 2

1

您有几个选项来记录类级别的变量。

  1. #:在变量之前或在同一行添加以开头的注释。（仅使用自动文档。）

    也许是最简单的选择。如果需要，您可以使用:annotation:选项自定义值。如果要键入提示值，请使用#: type:.

  2. 在变量之后放置一个文档字符串。

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

    对于模块数据成员和类属性，可以将文档放入具有特殊格式的注释中（使用#: 来开始注释而不是仅使用#），或者在定义之后的文档字符串中。注释需要在定义之前的一行中，或者在同一行的赋值之后。后一种形式仅限于一行。

  3. 在类文档字符串中记录变量。（使用 sphinx-napoleon 扩展，如示例所示。）

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

以下示例显示了所有三个选项。它.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."

结果：

在此处输入图像描述

于 2020-11-12T03:59:17.597 回答
0

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

class OSM2:
    sleep_time = 10;  """str: Inline docstring of sleep_time after the variable."""
于 2022-02-17T16:34:32.163 回答