Should Sphinx be able to document instance attributes in a class?

Question

I'm finding conflicting and often dated information so hoping someone can clear this up.

I'd like to document something like this using Sphinx:

class MyClass:
    """
    MyClass, which is documented with a docstring at the class level
    """
    classVar = None
    """A class var with an initial value and a 1-line doc"""

    def __init__(self):
        """
        __init__'s docs
        """
        instanceVar1 = 10
        """An instance var with an initial val and 1-line doc"""

        #: An instance var with an initial val and a doc-comment
        instanceVar2 = 10

In my docs, I'd like to see instanceVar1 and its docstring (ideally with its default value, but I'd be happy with just the description). But if I run with an rst file of:

.. automodule:: mymodule.mycode
   :members:

I only see the class attributes, not the instance attributes:

Googling gives me conflicting info on what should/shouldn't work. Several older stack overflow chains cite issues with autodocumentation for instance attributes (such as here) but they also refer to it working if you've added docstrings like I've done above. Sphinx docs cite that all attributes can be autodocumented.

Can anyone comment on whether what I'm trying to do should work/it works for them now you/suggestions on what I might have messed up? Thanks.

maybe I'm missing something, but isn't this the format described [here](http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoattribute) for bar, baz, quz, and spam? <-- response to a comment that is no longer here - deleted? — Andrew, Jun 20 '19 at 21:14
Automodule will only use docstrings, do you actually use autoattribute? FWIW I generally use http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html for more human-readable source code. — jonrsharpe, Jun 20 '19 at 21:20

john-hen · Accepted Answer · 2019-06-21T09:51:34.443

Yes, what you did should work, and it — eventually — worked for me.

To demonstrate, I'm using the example from the Sphinx docs that you cited:

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

I saved that as module.py and created the following index.rst:

.. automodule:: module

Along with this Sphinx configuration file, conf.py:

import sys
sys.path.insert(0, '.')
extensions = ['sphinx.ext.autodoc']
autodoc_default_options = {
    'members':         True,
    'member-order':    'bysource',
    'special-members': '__init__',
}

With all three files stored in the same folder, I ran Sphinx (2.1.1) via sphinx-build . ./html (on Python 3.7.3 and Windows 10) to render it as HTML:

As to what you "might have messed up"… Um, that's adequately put, as I'm sure you'll agree. ;-) It took me quite a while to realize this when, at first, I tried the same as above, but with the code example you provided: Your two alleged instance attributes, instanceVar1 and instanceVar2, are missing the self identifier in front. Oops. That's why it didn't work.

oh god that's embarrassing. No wonder I was pulling my hair out yesterday. I started with a real package (which actually used self...) where instance variables weren't doccing right, so I dumbed it down to the above example to troubleshoot. Turns out I accidentally added a mistake that replicates the same thing I was trying to troubleshoot! Haven't actually fixed my real module yet, but this gives me a working example! — Andrew, Jun 21 '19 at 13:00

Should Sphinx be able to document instance attributes in a class?

1 Answers1