使用sphinx的autodoc對屬性進行Docstring繼承

Question

我有一個這樣的課：

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

和另一個繼承它的類：

class MyObj(MyBase):
   x = 0

當我使用sphinx的autodoc生成文檔時， MyObj.x沒有記錄。 有沒有辦法從MyBase.x繼承docstring？ 我找到了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正確文檔，sphinx也可以正確地選擇它。

Answer 2

據我所知，屬性的docstrings不是Python的一部分。 當我嘗試它時， MyBase.x.__doc__沒有設置為它下面的字符串。 Docstrings僅適用於類，函數和方法。 如果Sphinx選擇x = 3下面的字符串作為文檔字符串，它可能會自己處理源代碼以獲得它。

Answer 3

如果您只關心通過Sphinx構建文檔。 你可以使用：“：inherited-members：”

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

這還將在Sphinx文檔中添加繼承成員的doc字符串。

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

Answer 4

正如托馬斯已經說過的，屬性在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.