Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Sphinx class attribute documentation

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?

like image 779
wonderb0lt Avatar asked Mar 28 '14 15:03

wonderb0lt


1 Answers

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!

like image 96
wonderb0lt Avatar answered Sep 29 '22 13:09

wonderb0lt