Sphinx生成PDF时未包含代码自动生成文档如何解决

问题原因 #

HTML构建正常但PDF仅包含手动编写的rst内容，核心是autodoc生成的代码文档未被纳入latex构建流程，常见诱因包括rst指令限制、配置缺失、路径错误、构建缓存问题四类。

解决步骤 #

1. 检查rst文档的autodoc指令 #

• 确认所有rst文件中的automodule/autoclass等autodoc指令未被.. only:: html条件块包裹，这类条件限制会让latex构建时直接跳过autodoc内容
• 确认所有包含autodoc内容的rst文件，都被根文档（通常是index.rst）的toctree指令引用，未被toctree纳入的文档不会出现在最终PDF中

2. 调整conf.py配置 #

补全autodoc默认规则

添加autodoc全局配置，确保代码成员默认被导出：

autodoc_default_options = {
    "members": True,
    "undoc-members": True,
    "special-members": "__init__",
    "show-inheritance": True,
}

修复导入路径

原路径配置为相对路径，若执行make命令的工作目录不是doc目录会导入失败，修改为绝对路径：

# 替换原有的sys.path.insert行
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))

补全latex依赖配置

原latex_elements缺少代码高亮、特殊字符渲染的必要包，更新为：

latex_elements = {
    "papersize": "letterpaper",
    "pointsize": "12pt",
    "preamble": r"""
\usepackage{setspace}
\usepackage{ctex} % 若文档包含中文需添加，编译时要改用xelatex
\usepackage{enumitem}
\setlistdepth{99} % 修复嵌套层级过深导致的编译错误
\usepackage{xcolor}
\definecolor{codegray}{gray}{0.95} % 代码块背景色
""",
    "extraclassoptions": "openany,oneside", # 可选，移除空白页
}
# 可选：明确指定latex根文档配置，避免默认配置遗漏
latex_documents = [
    ("index", "项目文档.tex", "项目文档", "作者名", "manual"),
]

3. 调整编译命令，清理缓存后构建 #

避免旧缓存导致的内容缺失，使用单步编译命令自动完成全流程：

make clean
make latexpdf

如果文档包含中文，需要修改build/latex目录下的Makefile，把默认的pdflatex改成xelatex再编译，否则中文会显示空白。

4. 排查编译警告 #

如果修改后仍然缺失内容，执行make latex时查看终端输出的警告：

• 若出现WARNING: autodoc: failed to import module，说明Python模块导入失败，需要排查路径、依赖是否完整
• 若出现latex编译警告，可查看build/latex目录下的log文件定位错误

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