本文详细介绍了在readthedocs平台配置自定义pdf生成并确保其在下载菜单中正确显示的方法。核心问题在于readthedocs对pdf文件的命名有特定要求。通过在`.readthedocs.yml`配置文件中，利用`mv`命令将生成的自定义pdf文件重命名为`$readthedocs_project.pdf`，可以解决pdf文件无法在readthedocs flyer菜单中被正确识别和下载的404错误，从而实现自定义pdf的无缝集成。
理解ReadTheDocs的PDF生成与展示机制
ReadTheDocs是一个广受欢迎的文档托管平台，它能够自动化构建Sphinx项目并提供HTML、PDF等多种格式的文档。通常，ReadTheDocs会自动生成一个PDF版本并将其链接到页面的下载（flyer）菜单中。然而，当用户尝试使用如sphinx-simplepdf这样的第三方扩展来生成高度定制化的PDF时，即使构建过程看似成功，生成的自定义PDF文件也可能不会出现在下载菜单中，点击PDF选项时甚至可能出现404错误。这通常是因为ReadTheDocs对默认PDF文件的命名和位置有特定的期望。
问题的根源：PDF文件命名不符合ReadTheDocs约定
当我们在.readthedocs.yml文件中通过自定义命令生成PDF时，例如使用sphinx-build -b simplepdf docs _readthedocs/pdf，虽然PDF文件会被正确生成到指定的_readthedocs/pdf目录，但其文件名可能与ReadTheDocs期望的默认文件名不符。ReadTheDocs通常期望在_readthedocs/pdf/目录下找到一个以项目名称命名的PDF文件，即$READTHEDOCS_PROJECT.pdf。如果找不到这个特定命名的文件，它就无法在下载菜单中正确链接，导致用户看到404错误。
解决方案：重命名自定义PDF文件
解决此问题的关键在于，在自定义PDF生成完成后，将其重命名为ReadTheDocs期望的格式。这可以通过在.readthedocs.yml文件的commands部分添加一个mv（move/rename）命令来实现。
下面是一个经过优化的.readthedocs.yml配置示例，它集成了sphinx-simplepdf扩展并确保生成的PDF文件能够被ReadTheDocs正确识别：
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# 设置Python版本和所需的其他工具
build:
os: ubuntu-20.04
tools:
python: "3.9"
# 添加自定义simple-pdf到readthedocs flyer菜单的命令
commands:
# 1. 安装文档构建所需的Python依赖
- pip install -r docs/requirements.txt
# 2. 清理_readthedocs/pdf目录，确保每次构建都是干净的
- rm -rf _readthedocs/pdf
# 3. 创建_readthedocs/pdf目录，用于存放生成的PDF文件
- mkdir -p _readthedocs/pdf
# 4. 使用sphinx-simplepdf扩展构建自定义PDF，输出到_readthedocs/pdf
- sphinx-build -b simplepdf docs _readthedocs/pdf
# 5. 删除_readthedocs/pdf目录中除.pdf文件以外的所有文件
- find _readthedocs/pdf -type f ! -name '*.pdf' -delete
# 6. 删除_readthedocs/pdf目录中除.pdf文件以外的所有子目录
- find _readthedocs/pdf -mindepth 1 -type d -delete
# 7. 创建_readthedocs/html/目录，用于存放HTML文档
- mkdir -p _readthedocs/html/
# 8. 构建HTML文档，输出到_readthedocs/html
- sphinx-build -b html docs _readthedocs/html
# 9. 关键步骤：将生成的PDF文件重命名为ReadTheDocs期望的格式
# $READTHEDOCS_PROJECT 是一个环境变量，代表当前项目的名称
- mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf
# 在docs/目录中使用Sphinx构建文档
sphinx:
configuration: docs/conf.py
# 如果使用Sphinx，可以选择构建其他格式的文档，如PDF
# 此处设置为all，但自定义PDF的优先级高于默认PDF
formats: all
# 可选声明构建文档所需的Python依赖
python:
install:
- requirements: docs/requirements.txt命令解析与注意事项
让我们详细分析commands部分的关键步骤：
- pip install -r docs/requirements.txt: 确保所有文档构建所需的Python包（包括sphinx-simplepdf）都已安装。
- rm -rf _readthedocs/pdf 和 mkdir -p _readthedocs/pdf: 清理并重新创建PDF输出目录，确保每次构建都是从干净状态开始。
- sphinx-build -b simplepdf docs _readthedocs/pdf: 这是使用sphinx-simplepdf扩展生成自定义PDF的核心命令。它会读取docs目录下的源文件，并以simplepdf构建器生成PDF文件，输出到_readthedocs/pdf目录。
- *`find _readthedocs/pdf -type f ! -name '.pdf' -delete和find _readthedocs/pdf -mindepth 1 -type d -delete**: 这些命令用于清理_readthedocs/pdf目录，确保只保留生成的PDF文件，删除可能由sphinx-build`生成的其他临时文件或空目录。这有助于保持输出目录的整洁。
- sphinx-build -b html docs _readthedocs/html: 正常构建HTML文档，这是ReadTheDocs最主要的功能。
- *`mv _readthedocs/pdf/.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf`: 这是解决问题的核心命令。**
- _readthedocs/pdf/*.pdf：匹配_readthedocs/pdf目录下所有以.pdf结尾的文件。假设simplepdf只生成一个PDF文件，这个通配符就能准确匹配。
- _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf：将匹配到的PDF文件重命名为$READTHEDOCS_PROJECT.pdf。$READTHEDOCS_PROJECT是ReadTheDocs提供的一个环境变量，它会自动替换为你的项目名称。例如，如果你的项目名为my-project，则PDF文件将被重命名为my-project.pdf。
总结
通过在.readthedocs.yml配置文件中添加一步简单的重命名操作，我们可以确保自定义生成的PDF文件符合ReadTheDocs的命名约定，从而使其在平台的下载菜单中正确显示。这个解决方案的关键在于理解ReadTheDocs对特定文件名的依赖，并利用其提供的环境变量$READTHEDOCS_PROJECT来动态构建正确的文件名。遵循此教程，开发者可以轻松地将高度定制化的PDF文档集成到ReadTheDocs平台，为用户提供更丰富的文档体验。
