Docstring inheritance for properties using sphinx's autodoc

Question

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?

Not to second guess you too much, but... your doc has the inheritance tree. Why wouldn't the user of `MyObj` just click the link to go to the parent object and then look at the parent object's documentation there? — Ross Rogers, Apr 01 '11 at 20:15
That's a possibility, but I think it's much nicer to have all of a class's methods and attributes (including inherited ones) on a single page instead of having to look through its type hierarchy. — jterrace, Apr 01 '11 at 20:33

jterrace · Accepted Answer · 2011-04-01T19:02:16.277

5

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.

edited Apr 01 '11 at 19:02

answered Apr 01 '11 at 18:42

jterrace

64,866
22
157
202

score 4 · Answer 2 · answered Apr 01 '11 at 17:18

4

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.

answered Apr 01 '11 at 17:18

Thomas K

39,200
7
84
86

This led me to think I should be using ``property()`` with the ``doc`` parameter. See my answer. It's kind of ugly, but I think it's probably the best way to do it, unless you have any better suggestions. – jterrace Apr 01 '11 at 18:43
@jterrace: I'm certainly not keen on turning x into a property with a getter just to add a docstring. I don't think there's another way to do it, but I generally leave attributes without a docstring, or describe the important ones in the class' docstring. – Thomas K Apr 01 '11 at 21:30
@Thomas-K: I agree, but the alternative is to duplicate the docstring which makes maintaining the documentation quite annoying. – jterrace Apr 01 '11 at 21:56

score 3 · Answer 3 · edited Jun 09 '19 at 23:13

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

edited Jun 09 '19 at 23:13

eyllanesc

235,170
19
170
241

answered Mar 17 '15 at 19:52

stephan schultchen

109
1
2

score 1 · Answer 4 · answered Dec 30 '13 at 12:18

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.

Docstring inheritance for properties using sphinx's autodoc

4 Answers4

Linked

Related