如何在Sphinx中选择性地为部分类生成私有成员函数的文档

我完全懂你的困扰——全局开启private-members后，所有类的私有函数一股脑都出现在文档里，乱糟糟的，而你只想让基类的私有成员（方便子类重写参考）显示出来对吧？别着急，有两个实用的办法可以解决这个问题：

方法一：在单个类的文档指令中单独设置选项 #

首先把conf.py里的全局默认设置改回不显示私有成员，这样大部分类就不会自动展示私有函数了：

autodoc_default_options = {
    "members": True,
    "undoc-members": False,
    "private-members": False  # 全局默认关闭
}

然后在你的.rst文档源文件里，针对需要展示私有成员的基类，在autoclass指令后面加上:private-members:参数就行。比如：

.. autoclass:: my_project.base_classes.MyBaseClass
    :members:
    :private-members:  # 单独给这个基类开启私有成员文档
    :undoc-members: False

这样只有这个基类会显示它的私有成员，其他类都遵循全局默认的规则，完美实现选择性展示。

方法二：用Sphinx的钩子函数自定义跳过逻辑 #

如果你的基类数量比较多，一个个手动加指令参数太麻烦，可以用Sphinx的autodoc-skip-member钩子函数，写个自定义规则来自动判断哪些私有成员要保留。

在conf.py里添加下面的代码：

def skip_private_members(app, what, name, obj, skip, options):
    # 这里可以自定义判断逻辑，比如：
    # 1. 判断当前处理的是类
    # 2. 判断这个类是你需要的基类（比如命名带Base，或者继承自某个特定父类）
    if what == 'class':
        # 示例：如果类名以Base开头，就不跳过它的私有成员（_开头的）
        if obj.__name__.startswith('Base'):
            # 只处理单下划线开头的私有成员，双下划线的特殊方法默认跳过
            if name.startswith('_') and not name.startswith('__'):
                return False  # 返回False表示不跳过，即要生成文档
    # 其他情况保持默认的跳过逻辑
    return skip

def setup(app):
    # 把自定义函数注册到Sphinx的钩子上
    app.connect('autodoc-skip-member', skip_private_members)

你可以根据自己的项目结构调整判断条件，比如改成判断类是否继承自某个基类issubclass(obj, MyBase)，这样更灵活。

小提示 #

• 注意区分单下划线_xxx（私有成员）和双下划线__xxx（名称修饰的特殊方法），一般后者不需要放进文档，所以钩子函数里特意排除了它们。
• 如果用方法一，要确保.rst文件里的指令参数和全局设置不冲突，比如全局已经开了members=True，就不用重复写啦。

备注：内容来源于stack exchange，提问作者KBriggs