本文详细阐述了在readthedocs项目中集成自定义pdf构建流程，并解决其在文档下载菜单中无法正确显示（404错误）的问题。核心解决方案在于，通过在`.readthedocs.yml`配置文件中添加一个文件重命名命令，将自定义生成的pdf文件统一命名为readthedocs期望的格式`$readthedocs_project.pdf`，从而确保pdf链接的正确性。
在ReadTheDocs平台发布技术文档时，除了默认的html格式，通常还需要提供PDF版本以方便用户离线阅读或打印。虽然ReadTheDocs提供了内置的PDF构建功能（通常基于LaTeX），但在某些特定场景下，例如需要使用sphinx-simplepdf等第三方Sphinx扩展来生成具有特定样式或布局的PDF时，就需要自定义PDF的构建流程。然而，即使自定义构建成功，生成的PDF文件也可能无法在ReadTheDocs的下载菜单（flyer menu）中正确显示，导致用户点击时出现404错误。本文将详细介绍如何配置.readthedocs.yml文件，以确保自定义生成的PDF能够正确集成并显示在ReadTheDocs的下载菜单中。
理解问题根源
当我们在.readthedocs.yml中通过自定义命令（如sphinx-build -b simplepdf）生成PDF文件时，这些文件会被放置在指定的输出目录（例如_readthedocs/pdf）。尽管构建过程可能显示成功，但ReadTheDocs平台在生成下载链接时，会预期PDF文件具有一个特定的命名约定，通常是项目名称.pdf。如果自定义生成的PDF文件名与此约定不符，即使文件存在于服务器上，ReadTheDocs也无法为其生成正确的下载链接，从而导致用户尝试下载时遇到404错误。
解决方案：文件重命名
解决此问题的关键在于，在自定义PDF构建完成后，将生成的PDF文件重命名为ReadTheDocs所期望的格式。ReadTheDocs在构建环境中提供了一个环境变量$READTHEDOCS_PROJECT，它包含了当前项目的名称。我们可以利用这个环境变量来动态地重命名PDF文件。
详细配置步骤
以下是修改后的.readthedocs.yml配置，它在原有自定义PDF构建流程的基础上，增加了一个关键的文件重命名步骤。
# .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: # 安装文档所需的Python依赖 - pip install -r docs/requirements.txt # 清理并创建自定义PDF的输出目录 - rm -rf _readthedocs/pdf - mkdir -p _readthedocs/pdf # 使用simplepdf扩展构建PDF文档 - sphinx-build -b simplepdf docs _readthedocs/pdf # 清理PDF输出目录，只保留.pdf文件 - find _readthedocs/pdf -type f ! -name '*.pdf' -delete - find _readthedocs/pdf -mindepth 1 -type d -delete # 创建并构建HTML文档 - mkdir -p _readthedocs/html/ - sphinx-build -b html docs _readthedocs/html # 关键步骤：重命名PDF文件以符合ReadTheDocs的命名约定 # 将生成的PDF文件重命名为 $READTHEDOCS_PROJECT.pdf - 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
关键命令解析
在上述配置中，最核心的改动是新增的这一行：
- mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf
- mv: 这是一个linux命令，用于移动或重命名文件。
- _readthedocs/pdf/*.pdf: 这表示在_readthedocs/pdf目录下找到所有以.pdf结尾的文件。假设simplepdf扩展只生成一个PDF文件，这个通配符会匹配到它。
- _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf: 这是目标文件名。$READTHEDOCS_PROJECT是ReadTheDocs构建环境提供的一个环境变量，其值是你的项目在ReadTheDocs上的名称。例如，如果你的项目名为my-awesome-project，那么PDF文件将被重命名为my-awesome-project.pdf。
通过这个重命名操作，无论sphinx-build -b simplepdf生成的文件最初叫什么名字，最终都会被统一命名为ReadTheDocs期望的格式，从而使其能够被正确地识别和链接到下载菜单中。
注意事项
-
确保simple-pdf扩展已安装并配置：在docs/conf.py中，你需要确保sphinx_simplepdf已经添加到extensions列表中，并且进行了必要的配置。
# docs/conf.py extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx_simplepdf', # 确保已添加 ] # simplepdf 相关配置 (示例，根据需求调整) simplepdf_theme = "furo" # 或其他你喜欢的主题 simplepdf_debug = True
-
formats: all：在.readthedocs.yml中设置formats: all是必要的，它会指示ReadTheDocs尝试生成所有支持的文档格式，并确保下载菜单的可见性。
-
单一PDF文件：上述重命名命令_readthedocs/pdf/*.pdf假设simplepdf构建过程只生成一个PDF文件。如果你的配置可能生成多个PDF，你需要调整重命名逻辑，以确保只有一个主PDF文件被重命名为$READTHEDOCS_PROJECT.pdf，或者根据需求管理多个PDF的链接。
-
清理中间文件：find _readthedocs/pdf -type f ! -name ‘*.pdf’ -delete 和 find _readthedocs/pdf -mindepth 1 -type d -delete 这两行命令用于清理PDF输出目录中的非PDF文件和子目录，确保最终目录只包含期望的PDF文件，这有助于保持输出目录的整洁。
总结
在ReadTheDocs中集成自定义PDF构建并确保其在下载菜单中正常显示，关键在于理解ReadTheDocs对PDF文件命名约定的期望。通过在.readthedocs.yml的构建命令中添加一个简单的文件重命名步骤，将自定义生成的PDF文件重命名为$READTHEDOCS_PROJECT.pdf，可以有效解决PDF无法下载（404错误）的问题。结合正确的Sphinx扩展配置和ReadTheDocs平台设置，你可以为用户提供高质量且可访问的自定义PDF文档。