ReadTheDocs自定义PDF集成教程：解决Flyer菜单404问题

本教程详细介绍了如何在readthedocs平台中集成自定义sphinx pdf文档，并解决其在flyer菜单中显示404错误的问题。核心在于通过`.readthedocs.yml`配置文件，在构建过程中将生成的pdf文件重命名为readthedocs平台期望的特定格式，确保用户能通过flyer菜单正常下载文档。

引言：自定义PDF与ReadTheDocs集成挑战

ReadTheDocs (RTD) 是一个广受欢迎的文档托管平台，它能够自动构建和发布使用Sphinx等工具生成的项目文档。通常，通过在.readthedocs.yml中设置formats: all，RTD会自动尝试生成HTML、EPUB和PDF格式的文档。然而，在某些情况下，开发者可能需要使用自定义的Sphinx扩展（例如sphinx-simplepdf）来生成具有特定样式或布局的PDF文档。

当采用这种自定义PDF生成方式时，一个常见的问题是：尽管RTD构建过程显示成功，生成的PDF文件在构建输出目录中也确实存在，但在RTD网站的Flyer（侧边栏）菜单中点击PDF下载链接时，却会遇到“404 Not Found”错误。这表明RTD未能正确识别或链接到我们自定义生成的PDF文件。

理解ReadTheDocs的PDF处理机制

ReadTheDocs在处理文档格式时，对特定文件路径和命名约定有要求。当用户点击Flyer菜单中的PDF选项时，RTD会尝试从一个预期的URL路径加载PDF文件。对于自定义生成的PDF，即使文件已成功构建到_readthedocs/pdf目录，如果其文件名不符合RTD的内部约定，RTD的Web服务器就无法找到它，从而导致404错误。

解决此问题的关键在于，确保我们自定义生成的PDF文件最终以RTD期望的特定文件名存在于其能够访问的目录中。RTD通常期望PDF文件以项目名称命名，例如_readthedocs/pdf/your_project_name.pdf。

配置.readthedocs.yml进行自定义PDF构建

要将自定义PDF集成到ReadTheDocs的Flyer菜单中，我们需要精心配置项目的.readthedocs.yml文件。这个文件是ReadTheDocs构建过程的核心指令集。

AI建筑知识问答

用人工智能ChatGPT帮你解答所有建筑问题

22

查看详情

以下是一个配置示例，展示了如何使用sphinx-simplepdf扩展来生成自定义PDF，并解决Flyer菜单404问题：

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

关键步骤：重命名PDF文件以供ReadTheDocs识别

上述配置中，解决404问题的核心在于这一行命令：

- mv _readthedocs/pdf/*.pdf _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf

这条命令的目的是：

1. *`_readthedocs/pdf/.pdf**: 查找_readthedocs/pdf目录下所有以.pdf结尾的文件。由于sphinx-build -b simplepdf通常会生成一个以文档根名命名的PDF文件（例如index.pdf`或项目名.pdf），这个通配符可以捕获它。
2. _readthedocs/pdf/$READTHEDOCS_PROJECT.pdf: 将找到的PDF文件重命名为$READTHEDOCS_PROJECT.pdf。
   • $READTHEDOCS_PROJECT 是ReadTheDocs提供的一个环境变量，它会自动替换为当前项目的名称。例如，如果你的项目在RTD上的URL是https://your-project.readthedocs.io，那么$READTHEDOCS_PROJECT的值就是your-project。
   • 通过这种方式，我们确保了最终的PDF文件名为your-project.pdf，这正是ReadTheDocs Flyer菜单期望的链接目标。

注意事项与最佳实践

1. sphinx-simplepdf扩展配置：
   • 确保你的docs/conf.py文件中正确安装并配置了sphinx-simplepdf扩展。这通常涉及在extensions列表中添加'sphinx_simplepdf'。
   • 根据sphinx-simplepdf的文档，你可能还需要在conf.py中添加或调整相关的配置选项，以控制PDF的样式和内容。
2. docs/requirements.txt的完整性：
   • 确保docs/requirements.txt文件包含了所有构建文档所需的Python包，特别是Sphinx和sphinx-simplepdf。
   • 示例：

     Sphinx
     sphinx-simplepdf
     # 其他Sphinx主题或扩展

     登录后复制
3. 本地测试：
   • 在将更改推送到ReadTheDocs之前，建议在本地环境中测试你的Sphinx构建过程。
   • 运行pip install -r docs/requirements.txt
   • 运行sphinx-build -b simplepdf docs _build/pdf
   • 运行sphinx-build -b html docs _build/html
   • 检查_build/pdf目录中是否生成了PDF文件，并且文件名是否符合预期。
4. 监控ReadTheDocs构建日志：
   • 在ReadTheDocs上触发构建后，务必仔细检查构建日志。日志会显示每一步命令的输出，包括潜在的错误信息。
   • 如果PDF下载仍然出现问题，日志是诊断问题的最佳起点。

总结

在ReadTheDocs中集成自定义Sphinx PDF文档并确保其在Flyer菜单中正确显示，关键在于理解RTD对PDF文件命名和路径的约定。通过在.readthedocs.yml的commands部分添加一个简单的mv命令，将自定义生成的PDF文件重命名为$READTHEDOCS_PROJECT.pdf，我们就能有效地解决“404 Not Found”问题，使用户能够顺利下载自定义的PDF文档。遵循本教程的步骤和注意事项，将帮助你成功实现这一集成。

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