Docstring inheritance for properties using sphinx&

问题:

I have a class like this:

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

and another class that inherits it:

class MyObj(MyBase):
   x = 0

When I use sphinx's autodoc to generate documentation, MyObj.x is not documented. Is there any way to inherit the docstring from MyBase.x? I found DocInherit but since this uses a decorator, it only works for class methods. Any way to do this with properties?

回答1:

I found a workaround using the property function:

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

class MyObj(MyBase):
   _x = 0

This is nice in that given an instance variable:

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

one can call help(m) and get proper documentation of property x and sphinx also picks this up correctly.

回答2:

As far as I know, docstrings for attributes are not part of Python. When I try it, MyBase.x.__doc__ does not get set to the string beneath it. Docstrings only work on classes, functions and methods. If Sphinx picks up the string underneath x = 3 as a docstring, it's probably doing its own processing of the source code to get that.

回答3:

If you only care for building Documentation via Sphinx. you can use: ":inherited-members:"

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

This will also add the doc strings of inherited members in Sphinx Documentation.

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

回答4:

As Thomas already stated, attributes do not have docstrings in Python. Sphinx however provides it's own processing allowing for attributes to be documented.

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

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

This results in:

class Test
    Bases: object

    test_attr = 'test'
        This is an attibute docstring.

    test_prop
        This is a property docstring.