如何用pydoc批量生成Python项目的HTML文档？

为什么指定目录时找不到文档？ #

pydoc使用-w参数+目录路径时，是按照Python模块导入规则查找解析模块的，不是直接扫描目录下的所有.py文件。这导致：

• src目录不在Python的sys.path中，pydoc无法将其识别为可导入的模块包
• 如果src目录没有__init__.py文件（哪怕是空文件），它也不会被pydoc当作合法Python包处理

而单独执行python3 -m pydoc .\src\main.py时，pydoc直接读取解析单个文件内容，不需要走模块导入流程，所以能正常生成文档。

pydoc是否支持批量生成文档？ #

支持，有两种可行方式：

1. 基于模块/包的批量生成：要求目标目录是合法Python包（含__init__.py）且已加入sys.path，此时用pydoc -w 包名就能批量生成该包下所有模块的文档
2. 遍历文件逐个生成：如果不想调整包结构，遍历目录下所有.py文件逐个调用pydoc的方式更可靠，也就是你目前考虑的方案，完全可行

具体解决方法 #

方法1：让pydoc识别src为合法包 #

• 先在src目录下创建空的__init__.py文件，将其标记为Python包
• 执行脚本前，把src所在的父目录加入PYTHONPATH环境变量：

  # Unix-like系统
  export PYTHONPATH=$(pwd):$PYTHONPATH
  # Windows系统
  set PYTHONPATH=%cd%;%PYTHONPATH%
  

• 调用pydoc时使用包名而非路径：

  subprocess.run(["python3", "-m", "pydoc", "-w", "src"])
  

  这样pydoc就能识别src下的所有模块并批量生成HTML文档

方法2：遍历文件逐个处理（推荐，无需调整项目结构） #

用glob遍历src下所有.py文件，逐个调用pydoc生成文档：

import glob
import subprocess

# 遍历src目录下所有.py文件（含子目录，不需要可去掉recursive=True）
py_files = glob.glob("./src/**/*.py", recursive=True)

for file in py_files:
    # 按需跳过无需生成文档的文件
    if "__pycache__" in file or file.endswith("__init__.py"):
        continue
    subprocess.run(["python3", "-m", "pydoc", "-w", file])

这个方法不受模块导入规则限制，能处理所有.py文件，适配任何项目结构

内容的提问来源于stack exchange，提问作者David Mould