Sphinx配置：将完整模块索引加入ReadTheDocs生成的PDF

问题背景 #

我用Sphinx autodoc生成Python项目文档并托管在ReadTheDocs上，但现在生成的PDF只显示首页目录，完全没包含完整的模块索引和所有模块/函数的文档内容。我希望能把首页目录和模块页面的内容合并到同一个PDF里，请问要修改conf.py里的哪些设置？

具体解决方案 #

别担心，调整几个配置就能搞定，我给你一步步说：

• 修改latex_documents配置
  默认情况下，Sphinx可能只把首页作为PDF的核心文档。你需要更新这个配置，指定首页作为PDF的主入口，后续配合toctree整合模块内容。示例代码如下：

  latex_documents = [
      (
          'index',  # 指定首页作为PDF的主入口
          'sensormotion.tex',
          'SensorMotion 项目文档',
          '你的名字',
          'manual'  # 文档类型保持manual即可
      ),
  ]
  

• 在首页index.rst里用toctree包含模块页面
  这一步是核心！你得在首页的rst文件里，把模块页面（比如sensormotion.rst）添加到toctree列表中，这样Sphinx生成PDF时才会自动抓取所有关联页面的内容。示例代码：

  .. toctree::
      :maxdepth: 2
      :caption: 完整文档
  
      source/sensormotion  # 这里填写你的模块页面相对路径
  

  如果有多个模块页面，也可以逐一添加，或者用:glob:匹配同类型文件。

• 检查autodoc的基础配置
  确保conf.py里已经正确启用autodoc扩展，并且模块路径设置正确——不然模块文档根本生成不出来，PDF自然也看不到。示例配置：

  extensions = [
      'sphinx.ext.autodoc',
      'sphinx.ext.viewcode',  # 可选，添加代码查看链接
      'sphinx.ext.napoleon',  # 可选，支持Google/Numpy风格注释
  ]
  
  # 将项目根目录加入Python路径，确保autodoc能找到你的模块
  import os
  import sys
  sys.path.insert(0, os.path.abspath('../..'))  # 根据你的项目结构调整路径
  

• 可选：调整latex_elements避免渲染问题
  有时候内容缺失可能是LaTeX渲染异常导致的，你可以在conf.py里添加必要的LaTeX包，确保复杂内容能正常渲染：

  latex_elements = {
      'preamble': r'''
          \usepackage{amsmath}
          \usepackage{amssymb}
          \usepackage{graphicx}
      ''',
  }
  

最后，把修改好的conf.py和index.rst提交到代码仓库，去ReadTheDocs后台重新触发一次构建，新生成的PDF就会包含完整的模块文档啦！

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