Sphinx 类属性文档

Question

我一直在尝试为我的MongoEngine应用程序写文档，但在记录我的文档类属性时遇到了问题。

我认为正确的写法应该是这样的：

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描述。

我是不是漏掉了什么Sphinx扩展？还是我写的语法有问题？

Answer 1

要把一个类的成员添加到文档中，可以使用 :members: 这个选项：

.. autoclass:: Asset
   :members:

如果不使用 :members:，那么文档中只会插入类的文档字符串，也就是类的介绍部分。

你还可以查看 autodoc_default_flags 这个配置选项。

---

你也可以用 autoattribute 来达到和上面一样的效果，而不需要 :members:（注意缩进）：

.. autoclass:: Asset

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

---

我无法重现这个问题，就是 uri 属性使用了 StringField 的文档字符串进行记录。

我使用的是 Sphinx 1.2.2 版本。

Answer 2

原来这个问题除了mzjn的回答外，还有其他原因：我需要完全写出我在使用..autoclass::的类的全名，才能让它正常工作，因为我在..currentmodule::中指定的模块是用from x import y这种方式导入的。也就是说，下面这种写法是可以正常工作的：

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

总之：检查你的导入语句！