解决ReadTheDocs自定义PDF在菜单中404错误的教程-Python教程-PHP中文网

解决ReadTheDocs自定义PDF在菜单中404错误的教程

聖光之護

发布： 2025-11-13 15:34:04

原创

540人浏览过

解决ReadTheDocs自定义PDF在菜单中404错误的教程

本文旨在解决readthedocs平台中，自定义pdf构建成功但无法通过侧边菜单下载（显示404错误）的问题。核心在于指导用户如何正确配置`.readthedocs.yml`文件，确保自定义生成的pdf文件能被readthedocs识别并正确链接。通过重命名pdf文件为项目特定名称，并将其放置在指定路径，可以有效解决此问题，确保用户能够顺利下载文档的pdf版本。

理解问题背景

在使用ReadTheDocs托管Sphinx项目时，开发者经常需要提供PDF版本的文档供用户下载。虽然ReadTheDocs默认支持生成PDF，但有时为了实现特定的样式或功能（例如使用sphinx-simplepdf等扩展），我们会选择自定义PDF的构建过程。然而，一个常见的问题是，即使自定义构建过程在ReadTheDocs上显示成功，用户点击侧边菜单中的PDF下载选项时，却可能遇到“404 Not Found”错误。这表明ReadTheDocs未能找到或正确链接到我们自定义生成的PDF文件。

问题根源分析

ReadTheDocs在提供下载链接时，通常会查找一个特定命名和位置的PDF文件。当自定义构建流程完成后，如果生成的PDF文件名或存放路径不符合ReadTheDocs的预期，即使文件实际存在于构建环境中，也无法通过其标准的下载机制访问。通常，ReadTheDocs期望在_readthedocs/pdf/目录下找到一个以项目名称命名的PDF文件，例如_readthedocs/pdf/$READTHEDOCS_PROJECT.pdf。

解决方案：正确配置.readthedocs.yml

解决此问题的关键在于确保自定义生成的PDF文件被正确命名，并放置在ReadTheDocs期望的位置。这可以通过在.readthedocs.yml配置文件中的commands部分添加一个重命名步骤来实现。

以下是详细的配置步骤和示例：

1. 确保构建环境和依赖

首先，确保你的构建环境已准备好，并且所有必要的Python依赖项都已安装。这通常通过pip install -r docs/requirements.txt命令完成。

# .readthedocs.yaml
version: 2

build:
  os: ubuntu-20.04
  tools:
    python: "3.9"
  commands:
    # 安装文档构建所需的Python依赖
    - pip install -r docs/requirements.txt
    # ... 其他命令 ...

登录后复制

2. 清理和准备PDF输出目录

在每次构建之前，清理并创建用于存放自定义PDF的目录是一个好习惯，以避免旧文件干扰。

# .readthedocs.yaml
# ...
  commands:
    - pip install -r docs/requirements.txt
    # 清理旧的PDF目录
    - rm -rf _readthedocs/pdf
    # 创建新的PDF目录
    - mkdir -p _readthedocs/pdf
    # ...

登录后复制

3. 执行自定义PDF构建

使用你选择的Sphinx构建器（例如simplepdf）来生成PDF。确保输出路径指向我们准备好的_readthedocs/pdf目录。

百度文心百中

百度大模型语义搜索体验中心

查看详情

# .readthedocs.yaml
# ...
  commands:
    - pip install -r docs/requirements.txt
    - rm -rf _readthedocs/pdf
    - mkdir -p _readthedocs/pdf
    # 使用simplepdf构建器生成PDF
    - sphinx-build -b simplepdf docs _readthedocs/pdf
    # ...

登录后复制

4. 清理非PDF文件（可选但推荐）

如果你的自定义PDF构建过程在输出目录中生成了除了.pdf文件之外的其他文件或子目录，可以使用find命令清理它们，确保目录只包含PDF文件。

# .readthedocs.yaml
# ...
  commands:
    - pip install -r docs/requirements.txt
    - rm -rf _readthedocs/pdf
    - mkdir -p _readthedocs/pdf
    - sphinx-build -b simplepdf docs _readthedocs/pdf
    # 删除_readthedocs/pdf中除.pdf文件外的所有文件
    - find _readthedocs/pdf -type f ! -name '*.pdf' -delete
    # 删除_readthedocs/pdf中所有子目录
    - find _readthedocs/pdf -mindepth 1 -type d -delete
    # ...

登录后复制

5. 构建HTML文档

通常，你还需要构建HTML版本的文档。

# .readthedocs.yaml
# ...
  commands:
    - pip install -r docs/requirements.txt
    - rm -rf _readthedocs/pdf
    - mkdir -p _readthedocs/pdf
    - sphinx-build -b simplepdf docs _readthedocs/pdf
    - find _readthedocs/pdf -type f ! -name '*.pdf' -delete
    - find _readthedocs/pdf -mindepth 1 -type d -delete
    # 创建HTML输出目录
    - mkdir -p _readthedocs/html/
    # 构建HTML文档
    - sphinx-build -b html docs _readthedocs/html
    # ...

登录后复制

6. 核心步骤：重命名PDF文件

这是解决404问题的关键步骤。将自定义构建生成的PDF文件重命名为${READTHEDOCS_PROJECT}.pdf。$READTHEDOCS_PROJECT是一个环境变量，在ReadTheDocs构建环境中会自动设置为你的项目名称。

# .readthedocs.yaml
# ...
  commands:
    - pip install -r docs/requirements.txt
    - rm -rf _readthedocs/pdf
    - mkdir -p _readthedocs/pdf
    - sphinx-build -b simplepdf docs _readthedocs/pdf
    - find _readthedocs/pdf -type f ! -name '*.pdf' -delete
    - find _readthedocs/pdf -mindepth 1 -type d -delete
    - mkdir -p _readthedocs/html/
    - sphinx-build -b html docs _readthedocs/html
    # 重命名生成的PDF文件为项目名称，并放置在正确的目录下
    - mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf

登录后复制

完整的.readthedocs.yml示例

结合以上所有步骤，一个完整的、可解决自定义PDF 404问题的.readthedocs.yml文件可能如下所示：

# .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:
    # 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
    - find _readthedocs/pdf -mindepth 1 -type d -delete
    # 5. 创建HTML输出目录并构建HTML文档
    - mkdir -p _readthedocs/html/
    - sphinx-build -b html docs _readthedocs/html
    # 6. 核心步骤：将生成的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确保ReadTheDocs会尝试处理所有格式，包括自定义的
formats: all

# Optionally declare the Python requirements required to build your docs
python:
  install:
    - requirements: docs/requirements.txt

登录后复制

注意事项

formats: all 的作用： 在readthedocs.yml中设置formats: all会告诉ReadTheDocs尝试生成所有支持的文档格式，包括PDF。虽然我们通过commands自定义了PDF的生成，但这个设置通常是推荐保留的，以确保ReadTheDocs的内部机制能够识别并处理PDF格式。
$READTHEDOCS_PROJECT 环境变量： 这是一个由ReadTheDocs提供的环境变量，它会自动包含你的项目名称。使用它可以确保PDF文件名与你的项目保持一致，无需手动修改。
sphinx-simplepdf 配置： 确保你的docs/conf.py文件中已正确配置了sphinx-simplepdf扩展，并且docs/requirements.txt中包含了sphinx-simplepdf。
构建日志： 在ReadTheDocs的构建日志中仔细检查每个命令的输出，特别是mv命令，确认PDF文件是否成功重命名。
单个PDF文件： 确保你的自定义构建过程最终只生成一个PDF文件。如果生成了多个，mv _readthedocs/pdf/*.pdf ...命令可能会有意外行为，或者只移动第一个匹配的文件。

总结

通过在.readthedocs.yml的commands部分添加一个简单的mv命令，将自定义生成的PDF文件重命名为${READTHEDOCS_PROJECT}.pdf并放置在_readthedocs/pdf/目录下，可以有效地解决ReadTheDocs侧边菜单PDF下载404的问题。这个解决方案确保了自定义构建的灵活性，同时满足了ReadTheDocs对PDF文件命名和路径的预期，从而为用户提供无缝的文档下载体验。

以上就是解决ReadTheDocs自定义PDF在菜单中404错误的教程的详细内容，更多请关注php中文网其它相关文章！