1. 首页
  2. 问题
  3. 构建失败：Readthedocs 中我的代码出现代码错误
小能豆

构建失败：Readthedocs 中我的代码出现代码错误

py

我正在尝试将我的 Sphinx 文档与 Readthedocs 链接起来。我可以在我的计算机上本地构建文档，但当我尝试让 Readthedocs 自动生成文档时，我收到以下错误：

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/helstrom-quantum-centroid-classifier/envs/latest/lib/python3.7/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/helstrom-quantum-centroid-classifier/envs/latest/lib/python3.7/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/helstrom-quantum-centroid-classifier/checkouts/latest/docs/conf.py", line 16, in <module>
    import sphinx_gallery
ModuleNotFoundError: No module named 'sphinx_gallery'

我哪里做错了？


阅读 20

收藏
2024-12-29

共1个答案

小能豆

该错误表明 Read the Docs 构建环境中缺少 sphinx_gallery 模块。以下是解决问题的步骤：

1. 确认本地构建依赖

确保 sphinx_gallery 在你的本地构建环境中安装，并且你在 conf.py 中使用它。通过以下命令确认：

pip freeze | grep sphinx-gallery

如果未安装，请运行：

pip install sphinx-gallery

2. 添加依赖到 requirements.txt

在项目的根目录中，创建或更新 requirements.txt 文件，添加 sphinx-gallery：

sphinx-gallery

如果你使用其他依赖（如 sphinx 或扩展），也应该添加它们。示例：

sphinx
sphinx-gallery

确保提交 requirements.txt 文件到版本控制系统（如 Git）。

3. 检查 readthedocs.yml 配置

如果项目使用 Read the Docs 的配置文件 .readthedocs.yml，确保正确指定了依赖文件。例如：

version: 2

sphinx:
  configuration: docs/conf.py

python:
  install:
    - requirements: requirements.txt
  • version: 2 是 Read the Docs 的最新配置文件格式。
  • requirements: requirements.txt 指定了需要安装的依赖。

4. 触发重新构建

确保将更改提交到 Git，并推送到远程仓库（如 GitHub）。然后在 Read the Docs 上重新构建文档：

  1. 转到项目的 Read the Docs 管理页面。
  2. 点击 Builds。
  3. 点击 Trigger Build。

5. 验证解决方案

构建完成后，检查是否仍然有错误。如果一切正常，Read the Docs 会成功生成文档。

6. 调试构建环境

如果问题仍然存在，可以使用以下方法调试 Read the Docs 构建环境：

  1. 转到 Read the Docs 管理页面。
  2. 点击 Builds，选择失败的构建。
  3. 查看构建日志，确认 pip install -r requirements.txt 是否正确执行，以及 sphinx-gallery 是否已安装。

通过这些步骤，你应该能够成功将 Sphinx 文档与 Read the Docs 集成。如果仍有问题，请提供更新的构建日志，我可以帮助进一步分析。

2024-12-29