解决ReadTheDocs自定义PDF无法在下载菜单显示的问题

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

解决ReadTheDocs自定义PDF无法在下载菜单显示的问题

2025-11-12

浏览次数：次

返回列表

解决ReadTheDocs自定义PDF无法在下载菜单显示的问题

本文详细介绍了在readthedocs平台配置自定义pdf生成并确保其在下载菜单中正确显示的方法。核心问题在于readthedocs对pdf文件的命名有特定要求。通过在`.readthedocs.yml`配置文件中，利用`mv`命令将生成的自定义pdf文件重命名为`$readthedocs_project.pdf`，可以解决pdf文件无法在readthedocs flyer菜单中被正确识别和下载的404错误，从而实现自定义pdf的无缝集成。

理解ReadTheDocs的PDF生成与展示机制

ReadTheDocs是一个广受欢迎的文档托管平台，它能够自动化构建Sphinx项目并提供HTML、PDF等多种格式的文档。通常，ReadTheDocs会自动生成一个PDF版本并将其链接到页面的下载（flyer）菜单中。然而，当用户尝试使用如sphinx-simplepdf这样的第三方扩展来生成高度定制化的PDF时，即使构建过程看似成功，生成的自定义PDF文件也可能不会出现在下载菜单中，点击PDF选项时甚至可能出现404错误。这通常是因为ReadTheDocs对默认PDF文件的命名和位置有特定的期望。

问题的根源：PDF文件命名不符合ReadTheDocs约定

当我们在.readthedocs.yml文件中通过自定义命令生成PDF时，例如使用sphinx-build -b simplepdf docs _readthedocs/pdf，虽然PDF文件会被正确生成到指定的_readthedocs/pdf目录，但其文件名可能与ReadTheDocs期望的默认文件名不符。ReadTheDocs通常期望在_readthedocs/pdf/目录下找到一个以项目名称命名的PDF文件，即$READTHEDOCS_PROJECT.pdf。如果找不到这个特定命名的文件，它就无法在下载菜单中正确链接，导致用户看到404错误。

解决方案：重命名自定义PDF文件

解决此问题的关键在于，在自定义PDF生成完成后，将其重命名为ReadTheDocs期望的格式。这可以通过在.readthedocs.yml文件的commands部分添加一个mv（move/rename）命令来实现。

下面是一个经过优化的.readthedocs.yml配置示例，它集成了sphinx-simplepdf扩展并确保生成的PDF文件能够被ReadTheDocs正确识别：

千鹿Pr助手

智能Pr插件，融入众多AI功能和海量素材

128 查看详情千鹿Pr助手

# .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"
  # 添加自定义simple-pdf到readthedocs flyer菜单的命令
  commands:
    # 1. 安装文档构建所需的Python依赖
    - pip install -r docs/requirements.txt
    # 2. 清理_readthedocs/pdf目录，确保每次构建都是干净的
    - rm -rf _readthedocs/pdf
    # 3. 创建_readthedocs/pdf目录，用于存放生成的PDF文件
    - mkdir -p _readthedocs/pdf
    # 4. 使用sphinx-simplepdf扩展构建自定义PDF，输出到_readthedocs/pdf
    - sphinx-build -b simplepdf docs _readthedocs/pdf
    # 5. 删除_readthedocs/pdf目录中除.pdf文件以外的所有文件
    - find _readthedocs/pdf -type f ! -name '*.pdf' -delete
    # 6. 删除_readthedocs/pdf目录中除.pdf文件以外的所有子目录
    - find _readthedocs/pdf -mindepth 1 -type d -delete
    # 7. 创建_readthedocs/html/目录，用于存放HTML文档
    - mkdir -p _readthedocs/html/
    # 8. 构建HTML文档，输出到_readthedocs/html
    - sphinx-build -b html docs _readthedocs/html
    # 9. 关键步骤：将生成的PDF文件重命名为ReadTheDocs期望的格式
    #    $READTHEDOCS_PROJECT 是一个环境变量，代表当前项目的名称
    - mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf

# 在docs/目录中使用Sphinx构建文档
sphinx:
  configuration: docs/conf.py

# 如果使用Sphinx，可以选择构建其他格式的文档，如PDF
# 此处设置为all，但自定义PDF的优先级高于默认PDF
formats: all

# 可选声明构建文档所需的Python依赖
python:
  install:
    - requirements: docs/requirements.txt

命令解析与注意事项

让我们详细分析commands部分的关键步骤：

pip install -r docs/requirements.txt: 确保所有文档构建所需的Python包（包括sphinx-simplepdf）都已安装。
rm -rf _readthedocs/pdf 和 mkdir -p _readthedocs/pdf: 清理并重新创建PDF输出目录，确保每次构建都是从干净状态开始。
sphinx-build -b simplepdf docs _readthedocs/pdf: 这是使用sphinx-simplepdf扩展生成自定义PDF的核心命令。它会读取docs目录下的源文件，并以simplepdf构建器生成PDF文件，输出到_readthedocs/pdf目录。
*`find _readthedocs/pdf -type f ! -name '.pdf' -delete和find _readthedocs/pdf -mindepth 1 -type d -delete**: 这些命令用于清理_readthedocs/pdf目录，确保只保留生成的PDF文件，删除可能由sphinx-build`生成的其他临时文件或空目录。这有助于保持输出目录的整洁。
sphinx-build -b html docs _readthedocs/html: 正常构建HTML文档，这是ReadTheDocs最主要的功能。
*`mv _readthedocs/pdf/.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf`: 这是解决问题的核心命令。**
- _readthedocs/pdf/*.pdf：匹配_readthedocs/pdf目录下所有以.pdf结尾的文件。假设simplepdf只生成一个PDF文件，这个通配符就能准确匹配。
- _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf：将匹配到的PDF文件重命名为$READTHEDOCS_PROJECT.pdf。$READTHEDOCS_PROJECT是ReadTheDocs提供的一个环境变量，它会自动替换为你的项目名称。例如，如果你的项目名为my-project，则PDF文件将被重命名为my-project.pdf。

总结

通过在.readthedocs.yml配置文件中添加一步简单的重命名操作，我们可以确保自定义生成的PDF文件符合ReadTheDocs的命名约定，从而使其在平台的下载菜单中正确显示。这个解决方案的关键在于理解ReadTheDocs对特定文件名的依赖，并利用其提供的环境变量$READTHEDOCS_PROJECT来动态构建正确的文件名。遵循此教程，开发者可以轻松地将高度定制化的PDF文档集成到ReadTheDocs平台，为用户提供更丰富的文档体验。