如何解决PyLaTeX生成PDF时目录为空的问题？

核心原因 #

LaTeX生成目录需要至少两次编译：第一次编译会收集所有章节/小节的位置信息并写入辅助文件（.aux），第二次编译才会根据辅助文件生成完整目录。你的代码只执行了一次编译，所以目录页只有标题没有内容。

解决方案 #

1. 增加编译次数 #

修改generate_pdf调用，添加compile_times=2参数，强制pdflatex编译两次：

doc.generate_pdf(filepath=filepath, compiler=pdflatex_path, clean_tex=True, compile_times=2)

如果文档结构复杂（比如包含交叉引用），可以设置为compile_times=3，确保所有引用和目录都正确生成。

2. 确保章节/小节的正确添加 #

确认你是用PyLaTeX提供的Section、Subsection类来添加章节内容，而非手动插入LaTeX命令，这样PyLaTeX才能正确标记这些结构供目录生成：

from pylatex import Document, Section, Subsection, NewPage, Command, NoEscape

# 创建文档实例
doc = Document()

# 添加章节和小节示例
with doc.create(Section('第一章 引言')):
    doc.append('这是第一章的内容')
    with doc.create(Subsection('1.1 研究背景')):
        doc.append('这是小节内容')

with doc.create(Section('第二章 方法')):
    doc.append('这是第二章的内容')

# 添加目录
doc.append(NewPage())
doc.append(Command('tableofcontents'))
doc.append(NoEscape(r'\clearpage'))

# 生成PDF并指定编译次数
doc.generate_pdf(filepath='test', compiler='pdflatex', clean_tex=True, compile_times=2)

3. 辅助文件排查（可选） #

如果问题仍存在，暂时将clean_tex=True改为clean_tex=False，编译后查看生成的.aux文件，确认其中是否有章节条目信息。如果没有，说明章节结构未被正确识别，需要检查章节添加的代码逻辑。

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