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

Question

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

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

.. automodule::
    :members:

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

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

.. automodule::
    :members: _PRIVATE_ATTR

我想避免为了添加这个私有成员而必须手动列出每个 public 成员。

有没有办法用 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 指令，但它不适用于模块级 "data members"。我发现autoattribute可以用来记录私有class属性，但是the documentation不清楚[=16=之间的确切区别] 和 autoattribute.

How to document a single private attribute with Sphinx autodoc?