使用 sphinx 的 autodoc 的属性的文档字符串继承答案

【问题标题】：Docstring inheritance for properties using sphinx's autodoc使用 sphinx 的 autodoc 的属性的文档字符串继承
【发布时间】：2011-04-01 16:15:18
【问题描述】：

我有这样的课：

class MyBase(object):
   x = 3
   """Documentation for property x"""

以及另一个继承它的类：

class MyObj(MyBase):
   x = 0

当我使用 sphinx 的 autodoc 生成文档时，MyObj.x 没有记录。有没有办法从MyBase.x 继承文档字符串？我找到了DocInherit，但由于它使用了装饰器，它只适用于类方法。有什么方法可以用属性做到这一点？

【问题讨论】：

不要过多地猜测你，但是......你的文档有继承树。为什么MyObj 的用户不直接点击链接转到父对象，然后查看父对象的文档？
这是一种可能性，但我认为将一个类的所有方法和属性（包括继承的）放在一个页面上会更好，而不必查看其类型层次结构。

标签： python python-sphinx autodoc

【解决方案1】：

我找到了使用属性函数的解决方法：

class MyBase(object):
   _x = 3
   x = property( lambda s: s._x, doc="Documentation for property x")

class MyObj(MyBase):
   _x = 0

这很好，因为给定了一个实例变量：

>>> m = MyObj()
>>> m.x
0

可以致电 help(m) 并获取属性 x 的正确文档，并且 sphinx 也可以正确选择。

【讨论】：

【解决方案2】：

据我所知，属性的文档字符串不是 Python 的一部分。当我尝试它时，MyBase.x.__doc__ 不会设置为它下面的字符串。文档字符串仅适用于类、函数和方法。如果 Sphinx 将 x = 3 下面的字符串作为文档字符串提取，它可能正在对源代码进行自己的处理以获取它。

【讨论】：

这让我觉得我应该使用 property() 和 doc 参数。看我的回答。这有点难看，但我认为这可能是最好的方法，除非你有更好的建议。
@jterrace：我当然不热衷于将 x 变成带有 getter 的属性，只是为了添加一个文档字符串。我认为没有其他方法可以做到这一点，但我通常会留下没有文档字符串的属性，或者在类的文档字符串中描述重要的属性。
@Thomas-K：我同意，但替代方法是复制文档字符串，这使得维护文档非常烦人。

【解决方案3】：

如果您只关心通过 Sphinx 构建文档。您可以使用： ":inherited-members:"

.. autoclass:: Noodle
   :members:
   :inherited-members:

这还将在 Sphinx 文档中添加继承成员的文档字符串。

http://sphinx-doc.org/ext/autodoc.html

【讨论】：

【解决方案4】：

正如 Thomas 已经说过的，属性在 Python 中没有文档字符串。然而，Sphinx 提供了它自己的处理，允许记录属性。

class Test(object):
    #: This is an attibute docstring.
    test_attr = 'test'

    @property
    def test_prop(self):
        """This is a property docstring."""

这会导致：

class Test
    Bases: object

    test_attr = 'test'
        This is an attibute docstring.

    test_prop
        This is a property docstring.

【讨论】：