Sphinx类属性文档

Question

我一直在尝试记录基于MongoEngine的应用程序,但是我在Document类上记录属性时遇到了问题.

我采用了正确的语法,如下所示:

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

我已经尝试过各种记录这些属性的方法,我发现这些属性甚至添加了一个不是MongoEngine字段的属性,只是为了确保这不是问题所在:

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 """

我已在相应的.rst文件中尝试了各种指令组合.目前它看起来像这样:

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

输出不是很令人满意:该foo属性根本没有显示文档,而uri字段有MongoEngine的"一个unicode字符串字段".(StringField该类文档)作为文档.此外,属性文档不会放在类的"下"(与automodule +:members: - 一起输出所有带有MongoEngine描述的字段)

我想念狮身人面像扩展吗？或者我搞砸了语法？

Answer 1

要将类的成员放入文档中,请使用以下:members:选项:

.. autoclass:: Asset
   :members:

没有:members:,只插入类docstring.

另请参阅autodoc_default_flags配置选项.

您可以使用autoattribute和不使用:members:(注意缩进)获得与上述相同的结果:

.. autoclass:: Asset

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

我无法uri使用StringField中的docstring 重现该属性被记录的问题.

我正在使用Sphinx 1.2.2.

Answer 2

事实证明，除了 mzjn 的回答之外，这个问题是由其他原因引起的：我必须完全限定我正在..autoclass::使用的类才能工作，因为我指定的模块..currentmodule::正在导入使用from x import y语法，即以下语法有效：

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

长话短说：检查您的进口！