Problems with autodoc and explicitly specified instance attributes

Question

I wrote a python class and I made the documentation with sphinx. For example, the class looks like :

class Aclass(object):
    """ my class """

    def __init__(self):
        """ constructor """

        self.a = None
        """ doc for attribute a """

        self._prop = None

    def _get_prop(self):
        """ getter prop """
        return self._prop

    def _set_prop(self, val):
        """ setter prop """
        self._prop = val

    prop = property(_get_prop, _set_prop)
    """ a property """

    def square(self):
        """ return square of a """
        return self.a**2

Now, in order to do the documentation, in the rst file I wrote :

.. autoclass:: aclass.Aclass
   :members:

All its ok, and a, prop and square appears in the doc.

But If I try to document attributes and methods separatly, sphinx says that it cannont find attribute a but it works for prop.

.. autoattribute:: aclass.Aclass.prop

.. autoattribute:: aclass.Aclass.a

The error message is :

Traceback (most recent call last):                                                                                
  File "/usr/lib/python2.7/dist-packages/sphinx/ext/autodoc.py", line 326, in import_object
    obj = self.get_attr(obj, part)
  File "/usr/lib/python2.7/dist-packages/sphinx/ext/autodoc.py", line 232, in get_attr
    return safe_getattr(obj, name, *defargs)
  File "/usr/lib/python2.7/dist-packages/sphinx/util/inspect.py", line 70, in safe_getattr
    raise AttributeError(name)
AttributeError: a

/home/gvallver/dev/sphinx/doc/source/index.rst:17: WARNING: autodoc can't import/find attribute 'aclass.Aclass.a', it reported error: "a", please check your spelling and sys.path

I read somewhere Sphinx values for attributes reported as None that sphinx do not isntantiate the class, thus there is a difference between class attribute (as prop) and instance attribute (as a). But how can I refer to instance attribute in the doc ?

Actually, instance attributes are found if they are not explicitly asked in the rst file. For example, this will work :

.. autoclass:: aclass.Aclass
    :members:

But this do not

.. autoclass: aclass.Aclass
    :members: a

Answer 1

There is a bug report about this (created 2012-03-30; still open 2015-12-12): https://github.com/sphinx-doc/sphinx/issues/904.

1. The problem with an explicit :members: list containing instance attributes was fixed in this commit (included in Sphinx 1.2b1).

2. As mentioned in a comment (from Jon Waltman), there is an undocumented autoinstanceattribute directive.

   Using .. autoinstanceattribute:: aclass.Aclass.a does work (tested with Sphinx 1.1.3 and 1.2b1).