新闻中心

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

2025-11-13
浏览次数：次
返回列表

解决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目录。

Perplexity Perplexity

Perplexity是一个ChatGPT和谷歌结合的超级工具，可以让你在浏览互联网时提出问题或获得即时摘要

Perplexity 302 查看详情 Perplexity 
# .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错误的教程的详细内容，更多请关注其它相关文章！


# html  # python  # 九台百度关键词排名企业  # 恩施推广引流网站  # 唐山网站seo优化服务  # 津市快照seo优化  # 咸宁农业网站推广员  # 企业网站的运营与推广论文  # 江西浆料网站建设费用  # 预防电信诈骗网站建设  # 丽水全网整合营销推广  # 泉州 seo  # 显存  # 所需  # 菜单中  # 目录下  # 命名为  # 重命名  # 是一个  # 文档  # 自定义  # red  # 配置文件  # 环境变量  # pdf  # ai  # ubuntu 


相关栏目： 【 科技资讯46185 】 【 网络学院92790 】


相关推荐： 为什么我的微信朋友圈看不到别人的更新_微信朋友圈更新显示异常解决方法  Win11怎么开启高性能模式_Windows 11电源计划优化设置  在J*a中如何开发简易电子商务商品管理系统_商品管理系统项目实战解析  Linux如何构建多环境配置管理_Linux多环境配置方案  windows10怎么查看本机ip_windows10命令提示符ipconfig使用  修复二维数组索引越界异常：一维循环到二维坐标的正确映射  QQ邮箱网页版入口页面 QQ邮箱在线登录入口官网  微博网页版首页入口 微博电脑端官网登录链接  2026春节假期时间安排 2026春节假日查询  哔哩哔哩忘记密码了怎么找回_哔哩哔哩密码找回方法  JUnit5/Mockito：优雅测试内部依赖与异常处理的实践  Excel文件在线转换快速入口 Excel在线格式转换网站  俄罗斯搜索引擎Yandex指南 附2025年免登录官网入口  谷歌浏览器怎么给标签页静音_Chrome标签静音快捷操作  LINUX下如何进行磁盘分区_fdisk与parted工具在LINUX中的使用对比  J*aScript设计模式实践_j*ascript代码优化  如何设置Windows Defender的定时扫描_计划任务实现自动杀毒【安全】  MinIO大规模对象列表性能瓶颈深度解析与外部元数据管理策略  Safari浏览器输入栏卡顿如何解决 Safari搜索建议与缓存清理  Golang如何使用new_Go new分配内存机制讲解  俄罗斯浏览器官网直达链接 俄罗斯浏览器最新在线入口导航  Windows 11怎么彻底关闭定位_Windows 11服务中禁用Geolocation  J*a里如何使用N*igableMap进行导航操作_可导航Map操作技巧解析  C#使用XPath查询节点时出错？ 常见语法错误与调试技巧  QQ邮箱网页版邮箱入口 QQ邮箱官方登录平台  外媒分析《GTA6》定价：卖100美元可以但真没必要！  “音游” × “怪文书” 题材的节奏冒险游戏 《晕晕电波症候群》确定于2026年4月发售！  Win10双系统截图高效法 截屏快捷键速记【技巧】  Yandex官方入口网址 Yandex俄罗斯搜索引擎最新在线地址  QQ邮箱官方网页版登录 QQ邮箱个人邮箱快速访问  CSS如何设置hover状态颜色_hover伪类调整背景或文字颜色  内存疯狂猛猛涨价：主板销量直接腰斩！  sublime怎么预览Markdown渲染效果_Markdown Preview插件 for sublime教程  深入理解J*aScript中的B样条曲线与节点向量生成  黑猫投诉统一入口官网 消费者权益保护投诉平台  Golang如何实现Web接口签名验证_Golang Web接口签名校验开发方法  Tabulator表格日期时间排序问题及自定义解决方案  QQ网页版官方账号入口 QQ网页版网页版登录指南  c++中的std::launder有什么实际用途_c++对象生命周期与指针优化  谷歌学术网站直达地址 谷歌学术搜索网页版一键进入  AI泡沫首次被“刺破”：GPU十年都无法存活！  抖音DOU+怎么投最有效 抖音付费推广的ROI提升技巧  AO3最新官网入口公告_2025AO3镜像站实时查询方法  如何创建独立于主系统的J*a运行环境_隔离式环境搭建策略  TikTok国际版网页端快速入口 TikTok全球版短视频浏览教程  整合Supabase认证与Django模型：跨模式迁移的解决方案  微信商城在哪里打开【步骤】  拼多多购物车商品数量无法修改如何处理 拼多多购物车操作优化方法  支付宝碰一碰设备是REDMI手机吗 博主拆机辟谣：处理器、内存都不一样  Win11输入法不见了怎么办_Windows11恢复语言栏显示方法 

上一篇：Python循环中列表追加与中断条件的执行顺序解析
下一篇：深入理解迭代囚徒困境策略生成：从理论到Python实现

搜索