20

我有一个类似于以下的 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 输出如下所示：

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

name 方向的唯一名称。

返回：方向名称

返回类型：字符串

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

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

4

1 回答 1

23

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

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

因此，类似以下的内容将以合理的方式呈现文档（如果需要getter，可以更改为任何其他文本）。settertype

@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

生成的文档如下所示：

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

name 方向的唯一名称。

Getter：返回此方向的名称

Setter：设置此方向的名称

类型：字符串

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

于 2013-07-08T08:28:59.450 回答