使用sphinx的autodoc实现属性的文档字符串继承

Question

我有一个这样的类：

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

还有另一个类是从它继承的：

class MyObj(MyBase):
   x = 0

当我使用sphinx的自动文档功能生成文档时，MyObj.x的说明没有被记录下来。有没有办法让它继承MyBase.x的说明呢？我找到了一种叫DocInherit的方式，但因为它是用装饰器实现的，所以只适用于类的方法。有没有办法让属性也能这样做呢？

Answer 1

如果你只想通过 Sphinx 来生成文档，可以使用这个选项：":inherited-members:"

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

这样做会把继承的成员的文档字符串也添加到 Sphinx 文档中。

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

Answer 2

据我所知，Python 中的属性是没有文档字符串的。当我尝试这样做时，MyBase.x.__doc__ 并不会被设置为它下面的字符串。文档字符串只适用于类、函数和方法。如果 Sphinx（一个文档生成工具）把 x = 3 下面的字符串当作文档字符串，那可能是它自己在处理源代码时得出的结果。

Answer 3

我找到了一种使用属性函数的解决办法：

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 也能正确识别这一点。