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

Question

我有一个Python类似于以下的内容，其中docstrings旨在由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输出结果大致如下：

class Direction(name) 可以进行移动的方向。

name 方向的唯一名称。

返回值： 方向名称

返回类型： 字符串

这在一定程度上可以，但请注意完全没有关于name设置器的任何信息。

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

- Matthew Murdoch

---

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

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

@MatthewMurdoch，Sphinx记录了getter而不使用()。这个和你结合的文档字符串一起，应该能帮助用户理解它是一个属性。 - Asclepius

@A-B-B 啊，我没意识到。谢谢！ - Matthew Murdoch

Answer 1

Sphinx忽略属性setter的文档字符串，因此属性的所有文档必须在@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

生成的文档大致如下：

class Direction(name) 可以进行移动的方向。

name 方向的唯一名称。

Getter: 返回此方向的名称

Setter: 设置此方向的名称

Type: 字符串

感谢 @BrenBarm 和 @A-B-B 指引我找到了这个解决方案。

- Matthew Murdoch