Question

我有一个类似于以下内容的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输出看起来像这样：

class 方向（姓名）   可以进行移动的方向。


命名     方向的唯一名称。


返回：方向名称

返回类型：字符串

尽管它很好，但请注意完全没有关于name setter的任何信息。

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

Answer 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

生成的文档如下所示：

class 方向（姓名）   可以进行移动的方向。


命名     方向的唯一名称。


Getter：返回此方向的名称

Setter：设置此方向的名称

输入：字符串

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

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

1 个答案: