本文旨在解决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.yamlversion: 2build: 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# Requiredversion: 2build: 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 Sphinxsphinx: 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 docspython: 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错误的教程的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1379842.html
微信扫一扫 
支付宝扫一扫 
