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

Question

我正在使用 sphinx 和 autodoc 扩展从 python 模块中的文档字符串自动生成文档。

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

.. automodule::
    :members:

我的模块还有许多私有属性。我想将其中之一包含在文档中。

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

.. automodule::
    :members: _PRIVATE_ATTR

我想避免仅仅为了添加这个私人成员而手动列出每一个公共成员。

有没有办法用 autodoc 来做到这一点？

Answer 1

这是我期望的工作（用 Sphinx 1.8.3 测试）：

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

但这并不完全有效。如果:private-members:给出该选项，无论带或不带参数，都将包含所有私有成员（前提是它们具有文档字符串）。

该:special-members:选项需要参数，所以很奇怪:private-members:没有参数。

相反，你可以使用autodata：

.. automodule:: yourmodule
   :members:

.. autodata:: yourmodule._PRIVATE_ATTR

autodata这是与“inside of”略有不同的替代方案automodule：

.. automodule:: yourmodule
   :members:

   .. autodata:: _PRIVATE_ATTR

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