本地构建Sphinx文档并添加PDF下载功能方法问询

一、启用ReadTheDocs主题的PDF下载按钮 #

ReadTheDocs主题自带下载按钮，但需要你本地生成PDF文件并告知主题其路径，具体步骤如下：

1. 安装必要依赖 #

• 安装ReadTheDocs主题：

  pip install sphinx-rtd-theme
  

• 安装LaTeX环境（用于生成PDF）：
  • Ubuntu/Debian：sudo apt-get install texlive-full
  • Windows：安装MikTeX
  • Mac：通过Homebrew安装mactex或直接下载安装MacTeX

2. 配置conf.py #

打开文档项目的conf.py，做以下修改：

• 设置主题为ReadTheDocs：

  html_theme = 'sphinx_rtd_theme'
  

• 添加html_context配置，指定PDF文件的相对路径（后续生成PDF后要放到对应位置）：

  html_context = {
      # 保留原有配置，新增PDF路径项
      'pdf_url': '_static/document.pdf',
  }
  

3. 生成PDF并同步到HTML目录 #

• 生成LaTeX源文件：

  sphinx-build -b latex ./source ./build/latex
  

• 进入LaTeX输出目录生成PDF：

  cd ./build/latex
  # Linux/Mac
  make pdf
  # Windows（确保pdflatex已加入系统PATH）
  pdflatex document.tex
  

• 将生成的PDF复制到HTML构建目录的_static文件夹（无此文件夹则新建）：

  cp ./build/latex/document.pdf ./build/html/_static/
  

4. 生成带PDF下载按钮的HTML #

重新生成HTML文档：

sphinx-build -b html ./source ./build/html

打开HTML页面后，即可看到右上角的PDF下载按钮。

二、本地模拟执行.readthedocs.yml #

.readthedocs.yml是ReadTheDocs平台的专属配置文件，无法直接本地运行，但可以手动模拟它的执行逻辑：

1. 解析.yml中的配置项 #

打开.readthedocs.yml，提取关键配置：

• Python版本：比如python: version: "3.10"
• 依赖安装规则：比如requirements: requirements.txt
• 构建命令：比如build: commands: ["sphinx-build -b html ./source ./build/html"]

2. 模拟环境与执行步骤 #

• 创建对应版本的Python虚拟环境：

  python3.10 -m venv rtd-env
  # 激活虚拟环境
  # Linux/Mac
  source rtd-env/bin/activate
  # Windows
  rtd-env\Scripts\activate
  

• 安装.yml中指定的依赖：

  pip install -r requirements.txt
  

• 执行.yml中定义的构建命令：
  按照配置里的命令依次运行，比如同时生成HTML和PDF：

  sphinx-build -b html ./source ./build/html
  sphinx-build -b latex ./source ./build/latex
  cd ./build/latex && make pdf
  

如果需要自动化，可将上述步骤写成shell脚本（Linux/Mac）或批处理脚本（Windows），一键执行。

内容的提问来源于stack exchange，提问作者Vincent Bénet