本文旨在解决readthedocs平台中，自定义pdf构建成功但无法通过侧边菜单下载（显示404错误）的问题。核心在于指导用户如何正确配置`.readthedocs.yml`文件，确保自定义生成的pdf文件能被readthedocs识别并正确链接。通过重命名pdf文件为项目特定名称，并将其放置在指定路径，可以有效解决此问题，确保用户能够顺利下载文档的pdf版本。
理解问题背景
在使用ReadTheDocs托管Sphinx项目时，开发者经常需要提供PDF版本的文档供用户下载。虽然ReadTheDocs默认支持生成PDF，但有时为了实现特定的样式或功能（例如使用sphinx-simplepdf等扩展），我们会选择自定义PDF的构建过程。然而，一个常见的问题是，即使自定义构建过程在ReadTheDocs上显示成功，用户点击侧边菜单中的PDF下载选项时，却可能遇到“404 Not Found”错误。这表明ReadTheDocs未能找到或正确链接到我们自定义生成的PDF文件。
问题根源分析
ReadTheDocs在提供下载链接时，通常会查找一个特定命名和位置的PDF文件。当自定义构建流程完成后，如果生成的PDF文件名或存放路径不符合ReadTheDocs的预期，即使文件实际存在于构建环境中，也无法通过其标准的下载机制访问。通常，ReadTheDocs期望在_readthedocs/pdf/目录下找到一个以项目名称命名的PDF文件，例如_readthedocs/pdf/$READTHEDOCS_PROJECT.pdf。
解决方案：正确配置.readthedocs.yml
解决此问题的关键在于确保自定义生成的PDF文件被正确命名，并放置在ReadTheDocs期望的位置。这可以通过在.readthedocs.yml配置文件中的commands部分添加一个重命名步骤来实现。
以下是详细的配置步骤和示例：
1. 确保构建环境和依赖
首先，确保你的构建环境已准备好，并且所有必要的Python依赖项都已安装。这通常通过pip install -r docs/requirements.txt命令完成。
# .readthedocs.yaml
version: 2
build:
os: ubuntu-20.04
tools:
python: "3.9"
commands:
# 安装文档构建所需的Python依赖
- pip install -r docs/requirements.txt
# ... 其他命令 ...2. 清理和准备PDF输出目录
在每次构建之前，清理并创建用于存放自定义PDF的目录是一个好习惯，以避免旧文件干扰。
# .readthedocs.yaml
# ...
commands:
- pip install -r docs/requirements.txt
# 清理旧的PDF目录
- rm -rf _readthedocs/pdf
# 创建新的PDF目录
- mkdir -p _readthedocs/pdf
# ...3. 执行自定义PDF构建
使用你选择的Sphinx构建器（例如simplepdf）来生成PDF。确保输出路径指向我们准备好的_readthedocs/pdf目录。
# .readthedocs.yaml
# ...
commands:
- pip install -r docs/requirements.txt
- rm -rf _readthedocs/pdf
- mkdir -p _readthedocs/pdf
# 使用simplepdf构建器生成PDF
- sphinx-build -b simplepdf docs _readthedocs/pdf
# ...4. 清理非PDF文件（可选但推荐）
如果你的自定义PDF构建过程在输出目录中生成了除了.pdf文件之外的其他文件或子目录，可以使用find命令清理它们，确保目录只包含PDF文件。
# .readthedocs.yaml
# ...
commands:
- pip install -r docs/requirements.txt
- rm -rf _readthedocs/pdf
- mkdir -p _readthedocs/pdf
- sphinx-build -b simplepdf docs _readthedocs/pdf
# 删除_readthedocs/pdf中除.pdf文件外的所有文件
- find _readthedocs/pdf -type f ! -name '*.pdf' -delete
# 删除_readthedocs/pdf中所有子目录
- find _readthedocs/pdf -mindepth 1 -type d -delete
# ...5. 构建HTML文档
通常，你还需要构建HTML版本的文档。
# .readthedocs.yaml
# ...
commands:
- pip install -r docs/requirements.txt
- rm -rf _readthedocs/pdf
- mkdir -p _readthedocs/pdf
- sphinx-build -b simplepdf docs _readthedocs/pdf
- find _readthedocs/pdf -type f ! -name '*.pdf' -delete
- find _readthedocs/pdf -mindepth 1 -type d -delete
# 创建HTML输出目录
- mkdir -p _readthedocs/html/
# 构建HTML文档
- sphinx-build -b html docs _readthedocs/html
# ...6. 核心步骤：重命名PDF文件
这是解决404问题的关键步骤。将自定义构建生成的PDF文件重命名为${READTHEDOCS_PROJECT}.pdf。$READTHEDOCS_PROJECT是一个环境变量，在ReadTheDocs构建环境中会自动设置为你的项目名称。
# .readthedocs.yaml
# ...
commands:
- pip install -r docs/requirements.txt
- rm -rf _readthedocs/pdf
- mkdir -p _readthedocs/pdf
- sphinx-build -b simplepdf docs _readthedocs/pdf
- find _readthedocs/pdf -type f ! -name '*.pdf' -delete
- find _readthedocs/pdf -mindepth 1 -type d -delete
- mkdir -p _readthedocs/html/
- sphinx-build -b html docs _readthedocs/html
# 重命名生成的PDF文件为项目名称，并放置在正确的目录下
- mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf完整的.readthedocs.yml示例
结合以上所有步骤，一个完整的、可解决自定义PDF 404问题的.readthedocs.yml文件可能如下所示：
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
build:
os: ubuntu-20.04
tools:
python: "3.9"
commands:
# 1. 安装文档构建所需的Python依赖
- pip install -r docs/requirements.txt
# 2. 清理并创建PDF输出目录
- rm -rf _readthedocs/pdf
- mkdir -p _readthedocs/pdf
# 3. 使用simplepdf构建器生成自定义PDF
- sphinx-build -b simplepdf docs _readthedocs/pdf
# 4. 清理PDF目录，只保留.pdf文件
- find _readthedocs/pdf -type f ! -name '*.pdf' -delete
- find _readthedocs/pdf -mindepth 1 -type d -delete
# 5. 创建HTML输出目录并构建HTML文档
- mkdir -p _readthedocs/html/
- sphinx-build -b html docs _readthedocs/html
# 6. 核心步骤：将生成的PDF重命名为项目名称，并放置在正确的目录下
- mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# If using Sphinx, optionally build your docs in additional formats such as PDF
# 这里的formats: all确保ReadTheDocs会尝试处理所有格式，包括自定义的
formats: all
# Optionally declare the Python requirements required to build your docs
python:
install:
- requirements: docs/requirements.txt注意事项
- formats: all 的作用： 在readthedocs.yml中设置formats: all会告诉ReadTheDocs尝试生成所有支持的文档格式，包括PDF。虽然我们通过commands自定义了PDF的生成，但这个设置通常是推荐保留的，以确保ReadTheDocs的内部机制能够识别并处理PDF格式。
- $READTHEDOCS_PROJECT 环境变量： 这是一个由ReadTheDocs提供的环境变量，它会自动包含你的项目名称。使用它可以确保PDF文件名与你的项目保持一致，无需手动修改。
- sphinx-simplepdf 配置： 确保你的docs/conf.py文件中已正确配置了sphinx-simplepdf扩展，并且docs/requirements.txt中包含了sphinx-simplepdf。
- 构建日志： 在ReadTheDocs的构建日志中仔细检查每个命令的输出，特别是mv命令，确认PDF文件是否成功重命名。
- 单个PDF文件： 确保你的自定义构建过程最终只生成一个PDF文件。如果生成了多个，mv _readthedocs/pdf/*.pdf ...命令可能会有意外行为，或者只移动第一个匹配的文件。
总结
通过在.readthedocs.yml的commands部分添加一个简单的mv命令，将自定义生成的PDF文件重命名为${READTHEDOCS_PROJECT}.pdf并放置在_readthedocs/pdf/目录下，可以有效地解决ReadTheDocs侧边菜单PDF下载404的问题。这个解决方案确保了自定义构建的灵活性，同时满足了ReadTheDocs对PDF文件命名和路径的预期，从而为用户提供无缝的文档下载体验。
