python - 使用 sphinx 的 autodoc 的属性的文档字符串继承

Question

我有这样的课：

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

和另一个继承它的类：

class MyObj(MyBase):
   x = 0

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

Answer 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狮身人面像也可以正确地找到它。

Answer 2

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

Answer 3

如果您只关心通过 Sphinx 构建文档。您可以使用：“：继承成员：”

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

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

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

Answer 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.