如何使用Sphinx autodoc记录单个私有属性？

Question

我使用sphinx和autodoc扩展从python模块中的docstring自动生成文档。

我目前使用automodule指令来记录该模块的所有公共成员。

.. automodule::
    :members:

我的模块也有许多私有属性。我想把其中一个写进文件里。

有没有一种方法可以告诉automodule记录所有的公共成员，以及这一个私有成员？我尝试过使用:private-members:选项，但这包括所有私有成员。我也尝试过手动指定私有属性，但是它没有记录任何公共成员。

.. automodule::
    :members: _PRIVATE_ATTR

我想避免手动列出每个公共成员，只为了添加这个私有成员。

有办法用autodoc做这个吗？

Answer 1

下面是我所期望的工作(用Sphinx1.8.3测试)：

.. automodule:: yourmodule
   :members:
   :private-members: _PRIVATE_ATTR

但这不太管用。如果给出了:private-members:选项，不管有没有参数，都会包含所有私有成员(前提是他们有一个docstring)。

:special-members:选项使用参数，所以:private-members:没有参数是很奇怪的。

相反，您可以使用autodata

.. automodule:: yourmodule
   :members:

.. autodata:: yourmodule._PRIVATE_ATTR

下面是一个略有不同的选择，autodata在“automodule”中

.. automodule:: yourmodule
   :members:

   .. autodata:: _PRIVATE_ATTR

还有一个autoattribute指令，但它不适用于模块级的“数据成员”。我发现autoattribute可以用来记录私有类属性，但是文献资料不清楚autodata和autoattribute之间的确切区别。