本教程详细指导如何在readthedocs平台中，将通过`sphinx-simplepdf`等工具生成的自定义pdf文件成功集成到下载菜单，并解决点击下载时出现的404错误。核心在于理解readthedocs对pdf文件命名和存放位置的约定，通过在`.readthedocs.yml`配置中正确重命名生成的pdf文件为`$readthedocs_project.pdf`，确保其能被readthedocs正确识别和提供下载，从而实现自定义pdf的无缝发布。
在ReadTheDocs平台上发布文档时，通常会同时生成HTML和PDF格式的输出。虽然ReadTheDocs提供了默认的PDF生成机制（通常基于LaTeX），但有时为了实现特定的样式、布局或功能，开发者可能需要使用自定义的PDF构建器，例如sphinx-simplepdf。然而，即便自定义PDF构建过程成功，用户也可能遇到PDF下载链接在ReadTheDocs菜单中显示为404错误的问题。本教程将深入探讨这一问题的原因，并提供一个完整的解决方案。
1. ReadTheDocs自定义PDF集成概述
ReadTheDocs是一个流行的文档托管服务，它通过解析项目的.readthedocs.yml配置文件来自动化文档的构建和部署。对于Sphinx项目，它默认支持HTML和PDF（通过LaTeX）输出。
当我们需要定制PDF的生成方式时，例如使用sphinx-simplepdf扩展来简化PDF的生成过程或实现特定的CSS样式，我们就需要在.readthedocs.yml文件中定义自定义的构建命令。这些命令会在ReadTheDocs的构建环境中执行，以生成所需的PDF文件。
2. 常见问题：自定义PDF下载链接404
许多用户在配置自定义PDF构建后，会发现ReadTheDocs的构建日志显示成功，但当他们点击ReadTheDocs界面上的“PDF”下载选项时，却收到一个“404 Not Found”错误。这表明尽管PDF文件可能已经在构建过程中生成，但ReadTheDocs服务未能将其正确地映射到可下载的链接。
问题的核心在于ReadTheDocs对可下载的PDF文件有特定的命名和路径期望。如果自定义构建的PDF不符合这些约定，即使文件实际存在于构建输出目录中，ReadTheDocs也无法将其正确识别并提供给用户下载。
3. 解决方案：优化.readthedocs.yml配置
解决此问题的关键在于确保自定义生成的PDF文件被重命名为ReadTheDocs所期望的格式，并放置在正确的输出目录中。ReadTheDocs期望主PDF文件名为$READTHEDOCS_PROJECT.pdf，其中$READTHEDOCS_PROJECT是一个环境变量，代表当前项目的名称。
以下是经过优化的.readthedocs.yml配置示例，其中包含了解决404问题的关键步骤：
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
os: ubuntu-20.04
tools:
python: "3.9"
# 添加自定义 simple-pdf 到 ReadTheDocs 下载菜单
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
# 5. 清理PDF输出目录，删除所有子目录
- find _readthedocs/pdf -mindepth 1 -type d -delete
# 6. 创建HTML输出目录（与PDF构建并行）
- mkdir -p _readthedocs/html/
# 7. 构建HTML文档
- sphinx-build -b html docs _readthedocs/html
# 8. 关键步骤：重命名自定义PDF文件为 ReadTheDocs 期望的格式
# 将生成的任何 .pdf 文件重命名为 $READTHEDOCS_PROJECT.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
# Optionally declare the Python requirements required to build your docs
python:
install:
- requirements: docs/requirements.txt关键命令解析：
- - pip install -r docs/requirements.txt: 这一步确保所有文档构建所需的Python包（包括sphinx-simplepdf）都被正确安装。
- - rm -rf _readthedocs/pdf 和 - mkdir -p _readthedocs/pdf: 在每次构建开始前，清理并重新创建_readthedocs/pdf目录，以确保构建环境的清洁和一致性。
- - sphinx-build -b simplepdf docs _readthedocs/pdf: 这是使用sphinx-simplepdf构建器生成PDF的命令。它将docs目录中的源文件构建成PDF，并输出到_readthedocs/pdf目录。
- - find _readthedocs/pdf -type f ! -name '*.pdf' -delete 和 - find _readthedocs/pdf -mindepth 1 -type d -delete: 这些命令用于清理_readthedocs/pdf目录，确保其中只包含最终的PDF文件，没有其他不必要的文件或子目录。这有助于保持输出目录的整洁。
- - mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf: 这是解决404问题的核心步骤。 它将_readthedocs/pdf目录中生成的任何PDF文件（通常只有一个）重命名为$READTHEDOCS_PROJECT.pdf。$READTHEDOCS_PROJECT是ReadTheDocs在构建环境中提供的一个环境变量，其值是你的项目名称。通过这种方式，ReadTheDocs能够准确地识别并提供这个PDF文件进行下载。
4. 注意事项与最佳实践
为了确保自定义PDF集成顺利，请注意以下几点：
-
conf.py配置： 确保你的docs/conf.py文件中已正确添加sphinx_simplepdf到extensions列表中，例如：
extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx_simplepdf', # 确保已添加 ] -
依赖管理： docs/requirements.txt文件必须包含sphinx-simplepdf。例如：
sphinx sphinx-rtd-theme sphinx-simplepdf # 其他依赖...
- 本地测试： 在将更改推送到ReadTheDocs之前，建议在本地环境中模拟构建过程。通过运行sphinx-build -b simplepdf docs _build/pdf等命令，检查PDF是否正确生成以及其命名是否符合预期。
- 环境变量理解： 了解ReadTheDocs提供的环境变量（如$READTHEDOCS_PROJECT）在自定义构建脚本中的应用，可以帮助你编写更健壮和通用的构建配置。
- formats: all： 在.readthedocs.yml中，formats: all指令告知ReadTheDocs尝试生成所有支持的文档格式，包括HTML和PDF。这对于确保PDF选项在菜单中可用是必要的。
5. 总结
将自定义PDF文件成功集成到ReadTheDocs的下载菜单中，关键在于理解并遵循ReadTheDocs对PDF文件命名和存放位置的约定。通过在.readthedocs.yml配置文件中，添加一个简单的mv命令来将自定义生成的PDF文件重命名为$READTHEDOCS_PROJECT.pdf，并确保其位于_readthedocs/pdf/目录下，即可解决点击PDF下载链接时出现的404错误。遵循本教程的步骤和最佳实践，你将能够顺利地发布包含自定义PDF输出的文档。
