本文详细阐述了在 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 文档。
