Sphinx class attribute documentation

Question

I've been trying to document my MongoEngine based application, but I'm having problems with documenting attributes on my Document classes.

I have taken the correct syntax for doing so is the following:

class Asset(Document):
     #: This is the URI of the document
     uri = StringField()

I've tried every way of documenting these attributes that I've found and even added an attribute that isn't a MongoEngine field just to make sure this isn't the issue:

class Asset(Document):
    """
    The representation of a file uploaded into the data store.
    """

    #: This is a test attribute.
    foo = 'bar'
    """baz?"""

    #: This is a URI.
    uri = StringField(required=True)
    """This is a URI """

I have tried out various combinations of directives in the corresponding .rst file. At the moment it looks like this:

.. currentmodule:: mymodule.asset
.. autoclass:: Asset
.. autoattribute:: Asset.foo
.. autoattribute:: Asset.uri

The output isn't very satisfying: The foo attribute has no documentation displayed at all and the uri field has MongoEngine's "A unicode string field." (the documentation of the StringField class) as documentation. Also the attribute documentation is not put "under" the class (as with automodule + :members: - which outputs all fields with their MongoEngine description)

Do I miss a Sphinx Extension? Or am I screwing up the Syntax?

Answer 1

It turns out this problem was caused, in addition to mzjn's answer by something else: I had to fully qualify the class I was ..autoclass::ing for it to work because the module I specified for ..currentmodule:: was importing used the from x import y syntax, i.e. the following syntax works:

.. currentmodule: mymodule.asset
.. autoclass: mymodule.asset.Asset
   :members:

Long story short: Check your imports!

Answer 2

To get the members of a class into the documentation, use the :members: option:

.. autoclass:: Asset
   :members:

Without :members:, only the class docstring is inserted.

See also the autodoc_default_flags configuration option.

---

You can get the same result as above with autoattribute and without :members: (note the indentation):

.. autoclass:: Asset

   .. autoattribute:: foo
   .. autoattribute:: uri

---

I cannot reproduce the problem that the uri attribute gets documented using the docstring from StringField.

I'm using Sphinx 1.2.2.