如何使用 Sphinx 为 Python 属性设置器生成文档？

Posted 2023-02-22

【中文标题】如何使用 Sphinx 为 Python 属性设置器生成文档？

【英文标题】：How can I generate documentation for a Python property setter using Sphinx?

【发布时间】：2013-07-02 22:00:12

【问题描述】：

我有一个类似于以下的 Python 类，其文档字符串旨在通过 Sphinx 转换为文档：

class Direction(object):
    """
    A direction in which movement can be made.
    """
    def __init__(self):
        self._name = None

    @property
    def name(self):
        """
        The unique name of the direction.

        :return: The direction name
        :rtype: string
        """
        return self._name

    @name.setter
    def name(self, value):
        """
        Sets the direction name.

        :param string value: The direction name
        """
        self._name = value

Sphinx 输出如下所示：

类 方向（名称） 可以移动的方向。

姓名 方向的唯一名称。

返回：方向名称

返回类型：字符串

就目前而言这很好，但请注意完全没有关于 name 设置器的任何信息。

有没有办法让 Sphinx 为属性设置器生成文档？

【问题讨论】：

如果 Sphinx 正在寻找它，那么在 getter 文档中记录任何特殊的 get/set 行为似乎更有意义。您在这里对 setter 的文档基本上是多余的：它是一个属性，因此它显然设置了值，并且记录参数也是不必要的，因为每个 setter 都需要相同的参数，并且实际上不会显式调用 setter。特殊的 get/set 行为实际上是整个属性的一个特征。属性的重点是通过单个属性名称访问它们，而不是单独的 get/set 函数调用。

@BrenBarn 如果这是 Sphinx 所期望的，我当然可以做到。但是，生成的文档实际上并没有表明它是一个属性，我不确定如何使用:param:、:return: 和:rtype: 标签来明确这一点？

@MatthewMurdoch，Sphinx 在不使用 () 的情况下记录了 getter。这与您的组合文档字符串一起，应该可以帮助用户理解它是一个属性。

@A-B-B 啊，我没有意识到这一点。谢谢！

【参考方案1】：

Sphinx 忽略属性设置器上的文档字符串，因此属性的所有文档都必须在 @property 方法上。

虽然 Sphinx 能够理解某些特定标签（例如 :param ...:），但它会接受任何自定义标签并将它们呈现为它们后面的文本的标签。

因此，以下内容将以合理的方式呈现文档（getter、setter 和 type 可以根据需要更改为任何其他文本）。

@property
def name(self):
    """
    The unique name of the direction.

    :getter: Returns this direction's name
    :setter: Sets this direction's name
    :type: string
    """
    return self._name

生成的文档如下所示：

类 方向（名称） 可以移动的方向。

姓名 方向的唯一名称。

Getter：返回此方向的名称

Setter：设置此方向的名称

类型：字符串

感谢@BrenBarm 和@A-B-B 为我指明了这个解决方案的方向。