python - 如何使用 Sphinx autodoc 记录单个私有(private)属性？

Question

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

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

.. automodule::
    :members:

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

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

.. automodule::
    :members: _PRIVATE_ATTR

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

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

Answer 1

这是我期望的工作(使用 Sphinx 1.8.3 测试):

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

但它并不完全有效。如果给出了 :private-members: 选项，无论有无参数，所有私有(private)成员都包括在内(前提是它们有文档字符串)。

:special-members: 选项接受参数，所以奇怪的是 :private-members: 没有。

相反，您可以使用 autodata:

.. automodule:: yourmodule
   :members:

.. autodata:: yourmodule._PRIVATE_ATTR

这是一个略有不同的替代方案，autodata“在”automodule 中:

.. automodule:: yourmodule
   :members:

   .. autodata:: _PRIVATE_ATTR

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