如何使用Sphinx autodoc文档化单个私有属性？

Question

我正在使用Sphinx和autodoc扩展来自动从我的Python模块的docstrings生成文档。

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

.. automodule::
    :members:

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

有没有办法告诉automodule文档化所有公共成员和这个私有成员？我尝试使用:private-members:选项，但那会包括所有私有成员。我也尝试手动指定私有属性，但那样就不会记录任何公共成员了。

.. automodule::
    :members: _PRIVATE_ATTR

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

是否可以使用autodoc来完成这个任务？

- Brendan Abel

---

你能提供一些背景信息吗——为什么你想要记录其中一个私有成员？那个文档可以放在类/模块级别，或者你可以将其公开，或者...？ - jonrsharpe

@jonrsharpe 私有成员有时在文档中很有用。我可以将私有属性的文档放在模块docstring中，但这意味着它将与其他属性和类（即内联）不同方式记录，并且在渲染的文档中具有不一致的排序。考虑到 :private-members: 是一个选项，似乎能够记录私有成员的子集并不是一个不切实际的期望。我不应该改变API只是为了正确呈现文档。 - Brendan Abel

好的，看起来Sphinx官方并不支持该功能。或者你可以使用:private-members: _what_you_want来实现。 - Sraw

@jonrsharpe，在Python文档中有__builtin__内建dunders和sunders。C#和Java API也相同，暴露内部以反映外部...那是个修辞问题吗？ - bad_coder

Answer 1

这是我期望的工作方式（已在Sphinx 1.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之间的确切区别。

- mzjn

---

我认为你说得很对，autodata 用于模块成员，而 autoattribute 用于类成员。根据 Sphinx 文档 的说明，“适用于模块数据成员和类属性”。 - Jacob Pavlock