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的“A unicode string field.”（StringField类的文档）作为文档。此外，属性文档未被放置在类“下方”（与automodule + :members:一样-它输出带有MongoEngine描述的所有字段）。

我是否缺少Sphinx扩展？或者我搞错了语法？

- wonderb0lt

Answer 1

使用:members:选项将类的成员添加到文档中。

.. autoclass:: Asset
   :members:

没有 :members:，仅会插入 类说明文档。

另请参阅 autodoc_default_flags 配置选项。

---

你可以通过使用autoattribute而无需:members:（注意缩进），获得与上述相同的结果：

.. autoclass:: Asset

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

---

我无法复现这个问题，即 uri 属性使用 StringField 的文档字符串进行文档化。

我正在使用 Sphinx 1.2.2。

- mzjn

---

嗨，这是问题的一部分，我已经在这里添加了自己的答案，解决了问题，并使“sphinx.ext.viewcode”扩展工作。好耶！ :) - wonderb0lt

Answer 2

原来，除了mzjn的回答之外，这个问题还由其他原因引起：我必须为我要进行 ..autoclass:: 的类进行全限定，以使其工作，因为我为 ..currentmodule:: 指定的模块在导入时使用 from x import y 语法。换句话说，以下语法是有效的：

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

长话短说：检查你的导入！

- wonderb0lt