pdoc 默认不包含以下划线开头的私有方法（如 _example_method），因其设计原则是仅暴露公共 API；但可通过自定义模板或修改模块的 __all__ 和 __pdoc__ 魔法变量显式控制文档可见性。

pdoc 默认不包含以下划线开头的私有方法（如 `_example_method`），因其设计原则是仅暴露公共 api；但可通过自定义模板或修改模块的 `__all__` 和 `__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__ 的过滤，但此处我们反向利用它配合显式声明）：

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

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

然后执行：

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

? 原理说明：--force 本身不直接启用私有成员，但它会绕过 __all__ 的白名单限制；而将私有名写入 __all__，再结合 --force，可确保 pdoc 在扫描时将其纳入候选集（后续仍受 __pdoc__ 最终裁决）。

❌ 不推荐的做法

• 修改 pdoc 源码或依赖未公开的内部标志（如 _pdoc_hidden）；
• 使用 --all-submodules 等开关试图“暴力覆盖”——它们控制的是包结构遍历，而非成员可见性；
• 重命名私有函数为公有（如 private_helper → helper），违背封装语义与 PEP 8 规范。

总结

pdoc 的设计强调 API 意图的明确表达。是否文档化私有函数，本质是接口设计问题：若该函数确需被下游用户理解或调试，应通过 __pdoc__ 显式授权；若纯属实现细节，则保持隐藏更利于长期维护。灵活运用 __pdoc__ 是最符合 pdoc 哲学、也最稳定可控的解决方案。