本教程详细介绍了如何在readthedocs平台中集成自定义sphinx pdf文档，并解决其在flyer菜单中显示404错误的问题。核心在于通过`.readthedocs.yml`配置文件，在构建过程中将生成的pdf文件重命名为readthedocs平台期望的特定格式，确保用户能通过flyer菜单正常下载文档。
引言：自定义PDF与ReadTheDocs集成挑战
ReadTheDocs (RTD) 是一个广受欢迎的文档托管平台，它能够自动构建和发布使用Sphinx等工具生成的项目文档。通常，通过在.readthedocs.yml中设置formats: all，RTD会自动尝试生成HTML、EPUB和PDF格式的文档。然而，在某些情况下，开发者可能需要使用自定义的Sphinx扩展（例如sphinx-simplepdf）来生成具有特定样式或布局的PDF文档。
当采用这种自定义PDF生成方式时，一个常见的问题是：尽管RTD构建过程显示成功，生成的PDF文件在构建输出目录中也确实存在，但在RTD网站的Flyer（侧边栏）菜单中点击PDF下载链接时，却会遇到“404 Not Found”错误。这表明RTD未能正确识别或链接到我们自定义生成的PDF文件。
理解ReadTheDocs的PDF处理机制
ReadTheDocs在处理文档格式时，对特定文件路径和命名约定有要求。当用户点击Flyer菜单中的PDF选项时，RTD会尝试从一个预期的URL路径加载PDF文件。对于自定义生成的PDF，即使文件已成功构建到_readthedocs/pdf目录，如果其文件名不符合RTD的内部约定，RTD的Web服务器就无法找到它，从而导致404错误。
解决此问题的关键在于，确保我们自定义生成的PDF文件最终以RTD期望的特定文件名存在于其能够访问的目录中。RTD通常期望PDF文件以项目名称命名，例如_readthedocs/pdf/your_project_name.pdf。
配置.readthedocs.yml进行自定义PDF构建
要将自定义PDF集成到ReadTheDocs的Flyer菜单中，我们需要精心配置项目的.readthedocs.yml文件。这个文件是ReadTheDocs构建过程的核心指令集。
以下是一个配置示例，展示了如何使用sphinx-simplepdf扩展来生成自定义PDF，并解决Flyer菜单404问题：
# .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"
# 自定义构建命令，用于生成simplepdf并将其上传到readthedocs flyer菜单
commands:
# 1. 安装文档所需的Python依赖
- pip install -r docs/requirements.txt
# 2. 清理并创建PDF输出目录
- rm -rf _readthedocs/pdf
- mkdir -p _readthedocs/pdf
# 3. 使用simplepdf builder生成PDF文档到指定目录
- sphinx-build -b simplepdf docs _readthedocs/pdf
# 4. 删除PDF输出目录中除.pdf文件外的所有文件，确保目录纯净
- find _readthedocs/pdf -type f ! -name '*.pdf' -delete
# 5. 删除PDF输出目录中除.pdf文件外的所有子目录
- find _readthedocs/pdf -mindepth 1 -type d -delete
# 6. 创建HTML输出目录并生成HTML文档
- mkdir -p _readthedocs/html/
- sphinx-build -b html docs _readthedocs/html
# 7. 关键步骤：将生成的PDF文件重命名为ReadTheDocs期望的格式
# $READTHEDOCS_PROJECT 是一个环境变量，代表当前项目的名称
- mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf
# 指定Sphinx配置文件的路径
sphinx:
configuration: docs/conf.py
# 告诉ReadTheDocs生成所有格式（虽然我们自定义了PDF，但保留此项通常无害）
formats: all
# Python环境配置
python:
install:
- requirements: docs/requirements.txt关键步骤：重命名PDF文件以供ReadTheDocs识别
上述配置中，解决404问题的核心在于这一行命令：
- mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf
这条命令的目的是：
- *`_readthedocs/pdf/.pdf**: 查找_readthedocs/pdf目录下所有以.pdf结尾的文件。由于sphinx-build -b simplepdf通常会生成一个以文档根名命名的PDF文件（例如index.pdf`或项目名.pdf），这个通配符可以捕获它。
-
_readthedocs/pdf/$READTHEDOCS_PROJECT.pdf: 将找到的PDF文件重命名为$READTHEDOCS_PROJECT.pdf。
- $READTHEDOCS_PROJECT 是ReadTheDocs提供的一个环境变量，它会自动替换为当前项目的名称。例如，如果你的项目在RTD上的URL是https://your-project.readthedocs.io，那么$READTHEDOCS_PROJECT的值就是your-project。
- 通过这种方式，我们确保了最终的PDF文件名为your-project.pdf，这正是ReadTheDocs Flyer菜单期望的链接目标。
注意事项与最佳实践
-
sphinx-simplepdf扩展配置：
- 确保你的docs/conf.py文件中正确安装并配置了sphinx-simplepdf扩展。这通常涉及在extensions列表中添加'sphinx_simplepdf'。
- 根据sphinx-simplepdf的文档，你可能还需要在conf.py中添加或调整相关的配置选项，以控制PDF的样式和内容。
-
docs/requirements.txt的完整性：
- 确保docs/requirements.txt文件包含了所有构建文档所需的Python包，特别是Sphinx和sphinx-simplepdf。
- 示例：
Sphinx sphinx-simplepdf # 其他Sphinx主题或扩展
-
本地测试：
- 在将更改推送到ReadTheDocs之前，建议在本地环境中测试你的Sphinx构建过程。
- 运行pip install -r docs/requirements.txt
- 运行sphinx-build -b simplepdf docs _build/pdf
- 运行sphinx-build -b html docs _build/html
- 检查_build/pdf目录中是否生成了PDF文件，并且文件名是否符合预期。
-
监控ReadTheDocs构建日志：
- 在ReadTheDocs上触发构建后，务必仔细检查构建日志。日志会显示每一步命令的输出，包括潜在的错误信息。
- 如果PDF下载仍然出现问题，日志是诊断问题的最佳起点。
总结
在ReadTheDocs中集成自定义Sphinx PDF文档并确保其在Flyer菜单中正确显示，关键在于理解RTD对PDF文件命名和路径的约定。通过在.readthedocs.yml的commands部分添加一个简单的mv命令，将自定义生成的PDF文件重命名为$READTHEDOCS_PROJECT.pdf，我们就能有效地解决“404 Not Found”问题，使用户能够顺利下载自定义的PDF文档。遵循本教程的步骤和注意事项，将帮助你成功实现这一集成。
