如何在 pdoc 中为私有函数生成文档
pdoc默认屏蔽以下划线开头的私有函数，不生成文档。可通过定义模块级__pdoc__字典，将私有成员映射为True，从而显式启用文档化；另一种方式是通过__all__列表配合--force参数实现。推荐使用__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 初衷、也最稳定可控的解决方案。
Photoshop 2026 是 Adobe 推出的专业图像处理与视觉设计软件，支持 Windows、macOS 和 iPad 等平台，广泛应用于摄影修图、电商设计、平面海报、数字绘画及视觉合成等创作场景。
Blender 是一款免费开源、跨平台的专业 3D 创作软件，集建模、动画、渲染、视频编辑与视觉合成等功能于一体，广泛应用于影视动画、游戏设计和建筑可视化等领域。软件支持 Cycles 物理渲染器与 Eevee 实时渲染引擎，并提供多边形建模、骨骼绑定、物理模拟等专业工具。Blender 兼容 Windows、macOS 和 Linux 系统，安装包轻巧、运行流畅，依托活跃的全球开发者社区持续更新，是从初学者到专业创作者都值得选择的正版 3D 创作工具。
极度公式是一款跨平台专业LaTeX公式识别编辑软件，支持OCR公式识别和多平台编辑。和使用说明，避免使用，享受完整功能与稳定支持。做扫描整理、文字提取和表格转换时，它能把识别后的处理步骤接得更顺，资料录入这类场景会省下不少时间。
一款文字处理软件，一种订阅式的跨平台办公软件，基于云平台提供多种服务，通过将 Excel 和 Outlook 等应用与 OneDrive 和 Microsoft Teams 等强大的云服务相结合，Office 365 可让任何人使用任何设备随时随地创建和共享内容。
CodeExpander 是一款快捷短语输入增强工具，通过键入缩写自动展开为自定义文段，提升工作效率。任务管理和过程控制会更完整，持续下载、批量同步或需要稳定传输流程的场景会更适合它。
Mountain Duck 是一款能将多个网盘挂载到本地的工具，像本地磁盘一样使用网盘。清理链路的完整性会更好一些，做应用卸载、残留处理和空间整理时，通常能少走很多手动排查步骤。
Photoshop 2026 是 Adobe 推出的专业图像处理与视觉设计软件，支持 Windows、macOS 和 iPad 等平台，广泛应用于摄影修图、电商设计、平面海报、数字绘画及视觉合成等创作场景。
Blender 是一款免费开源、跨平台的专业 3D 创作软件，集建模、动画、渲染、视频编辑与视觉合成等功能于一体，广泛应用于影视动画、游戏设计和建筑可视化等领域。软件支持 Cycles 物理渲染器与 Eevee 实时渲染引擎，并提供多边形建模、骨骼绑定、物理模拟等专业工具。Blender 兼容 Windows、macOS 和 Linux 系统，安装包轻巧、运行流畅，依托活跃的全球开发者社区持续更新，是从初学者到专业创作者都值得选择的正版 3D 创作工具。
极度公式是一款跨平台专业LaTeX公式识别编辑软件，支持OCR公式识别和多平台编辑。和使用说明，避免使用，享受完整功能与稳定支持。做扫描整理、文字提取和表格转换时，它能把识别后的处理步骤接得更顺，资料录入这类场景会省下不少时间。
一款文字处理软件，一种订阅式的跨平台办公软件，基于云平台提供多种服务，通过将 Excel 和 Outlook 等应用与 OneDrive 和 Microsoft Teams 等强大的云服务相结合，Office 365 可让任何人使用任何设备随时随地创建和共享内容。
Wise Folder Hider Pro 是一款专业级文件和文件夹隐藏加密软件，为私密数据添加多重保护。高频操作更强调就近处理，浏览、整理和跨目录移动文件时，来回切换和重复点击都会少很多。
CodeExpander 是一款快捷短语输入增强工具，通过键入缩写自动展开为自定义文段，提升工作效率。任务管理和过程控制会更完整，持续下载、批量同步或需要稳定传输流程的场景会更适合它。