Sphinx Class Attribute Documentation

Question

I tried to document my MongoEngine application, but I am having problems documenting attributes in my Document classes.

I took the correct syntax to do the following:

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

I tried every way to document these attributes that I found, and even added an attribute that is not a MongoEngine field to make sure this is not a problem:

 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 tried 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 result is not very satisfactory: the foo attribute has no documentation at all, and in the uri field there is MongoEngine "Unicode string string". (StringField class documentation) as documentation. In addition, attribute documentation does not fit under the "class" (as with automodule +: members: - which displays all fields with MongoEngine descriptions)

Am I missing the Sphinx extension? Or am I twisting the syntax?

Answer 1

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

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

In short: Check your import!

Answer 2

To get class members in the documentation, use the :members: parameter

 .. autoclass:: Asset :members: 

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

See also autodoc_default_flags configuration autodoc_default_flags .

---

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

 .. autoclass:: Asset .. autoattribute:: foo .. autoattribute:: uri 

---

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

I am using Sphinx 1.2.2.