在 sphinx 文档中选择性地包含私有成员函数

Question

我想为 python 项目自动生成文档。我设法获得了一个与 sphinx 一起使用的准系统管道，但输出目前几乎包括所有内容，我希望对类成员和方法方面记录的内容和未记录的内容更有选择性。

特别是，我想记录某些类（基类，以便子类化它们的人们可以访问他们需要重写的函数的完整描述）的“私有”成员函数，但不是全部。互联网向我指出了

:private-members:

，但它的使用会导致错误并且不会生成任何文档。我设法通过在

conf.py

中设置默认行为来使其工作：

extensions = ['sphinx.ext.autodoc']

autodoc_default_options = {
    "members": True,
    "undoc-members": False,
    "private-members": True}

但这普遍适用，我不希望所有类都记录私有成员。我怎样才能实现这个目标？

为了清晰起见，进行编辑。

如果我删除

autodoc_default_options

中的

conf.py

定义，我可以用

index.rst

来编译它，如下所示：

.. automodule:: app.utils.MetaReader
    :private-members:
.. automodule:: app.utils.MetaWriter
    :private-members:
.. automodule:: app.utils.MetaFilter
    :private-members:
.. automodule:: app.utils.MetaEventFinder
    :private-members:
.. automodule:: app.plugins.filters.BesselFilter
    :members:   
.. automodule:: app.plugins.datareaders.ChimeraReader20240101
    :members:   
.. automodule:: app.plugins.datareaders.ChimeraReader20240501
    :members:   
.. automodule:: app.plugins.datawriters.Pod5Writer
    :members:   
.. automodule:: app.plugins.eventfinders.ClassicBlockageFinder
    :members:   
.. automodule:: app.models.main_model
    :private-members:   
.. automodule:: app.models.reader
    :private-members:   
.. automodule:: app.controllers.file_load_controller
    :private-members:   
.. automodule:: app.controllers.main_controller
    :private-members:   
.. automodule:: app.views.file_load_view
    :private-members:   
.. automodule:: app.views.main_view
    :private-members:   
.. automodule:: app.views.raw_data_view
    :private-members:   

但是，据我所知，带有

:private-members:

指示的模块提供与仅带有

:members:

的模块相同的输出 - 并且在这两种情况下，私有成员函数都不属于生成的文档的一部分。

如果我同时添加

:private-members:

和

:members:

，我会收到以下错误：

reading sources... [100%] index
WARNING: missing attribute mentioned in :members: option: module app.utils.MetaReader, attribute :members:

（+所有其他模块都出现相同的错误）

Answer 1

通过查看您想要自动记录的内容的名称，我认为您正在尝试

automodule

一个类，而不是

autoclass

一个类。