如何在 pdoc 中为私有函数生成文档

pdoc 默认会屏蔽所有以下划线开头的私有方法（比如 `_example_method`），因为它的设计原则是“只暴露公共 API”。但如果你确实需要让某些私有函数在文档中现身，可以通过自定义模板或修改模块的 `__all__` 和 `__pdoc__` 魔法变量来显式控制可见性。

pdoc 有个默认行为：它会忽略所有以下划线开头的私有方法。这背后的逻辑其实很清晰——pdoc 信奉“文档即接口”，只记录那些符合 Python 公共约定的成员（即没有下划线前缀、且未被 __all__ 显式排除的可导出对象）。所以，哪怕你用了 --all-modules 或者设置了 PODOC_ALL_SUBMODULES=true，这些开关影响的也只是子模块的加载范围，并不改变类或模块内部成员的可见性判定规则。

那么，如果确实需要让私有函数（比如 _helper() 或 __internal_process()）出现在最终生成的 HTML 文档中，该怎么办？推荐下面两种轻量且好维护的方案。

✅ 方法一：使用 __pdoc__ 显式启用（推荐）

在模块的顶层（比如 mymodule.py）添加一个 __pdoc__ 字典，把你想文档化的私有成员映射为 True：

# mymodule.py
def public_func():
    """这是一个公开函数，会自动被文档化。"""
    pass

def _private_helper():
    """这是一个私有辅助函数。"""
    return 42

# 显式声明需文档化的私有成员
__pdoc__ = {
    '_private_helper': True,
    # 也可禁用某个公有成员：'public_func': False,
}

然后运行命令即可生效：

pdoc --html --output-dir docs mymodule

⚠️ 注意：__pdoc__ 必须定义在待文档化模块的全局作用域，并且要放在目标函数定义之后，否则可能因为导入顺序问题导致识别失败。

✅ 方法二：通过 __all__ + --force 组合（适用于模块级私有函数）

如果你的私有函数本质上是“模块内可用但并非严格私有”，可以考虑把它加入 __all__，再配合 --force 强制包含。注意这里的逻辑有点巧妙：--force 本身会绕过 __all__ 的白名单限制，而你把私有名写进 __all__ 后，再结合 --force，就能确保 pdoc 在扫描时将其纳入候选集——当然，最终是否显示还是受 __pdoc__ 的裁决。

# mymodule.py
__all__ = ['public_func', '_private_helper']  # 将私有名列入 __all__

def public_func(): ...
def _private_helper(): ...

然后执行：

pdoc --force --html --output-dir docs mymodule

? 原理说明：--force 不直接启用私有成员，但它会绕过 __all__ 的限制；而 __all__ 里写上私有名，相当于给 pdoc 一个“候选名单”。最终谁上场，还是 __pdoc__ 说了算。

❌ 不推荐的做法

• 修改 pdoc 源码或依赖未公开的内部标志（比如 _pdoc_hidden）；
• 试图用 --all-submodules 之类的开关“暴力覆盖”——它们控制的是包结构遍历，跟成员可见性不沾边；
• 把私有函数改名为公有（比如 private_helper → helper），这既违背封装语义，也不符合 PEP 8 规范。

总结

pdoc 的设计哲学很明确：API 的意图要清晰表达。是否文档化私有函数，本质上是一个接口设计问题——如果这个函数确实需要被下游用户理解或调试，那就通过 __pdoc__ 显式授权；如果它纯属实现细节，保持隐藏反而更有利于长期维护。灵活运用 __pdoc__ 是最符合 pdoc 初衷、也最稳定可控的解决方案。