本地可构建的Sphinx RTD文档上传至Read the Docs构建失败求助

排查步骤 #

• 核对.readthedocs.yaml的依赖配置路径：
  确保yaml中指定的requirements路径完全匹配项目结构，比如requirements.txt在docs/目录下时，配置应如下：

  version: 2
  
  build:
    os: ubuntu-22.04
    tools:
      python: "3.10"
  
  python:
    install:
      - requirements: docs/requirements.txt
  

  检查是否存在拼写错误，比如把docs写成doc，或者路径分隔符使用错误。

• 确认requirements.txt依赖完整性：
  除myst-parser==0.18.1外，需明确列出Sphinx及主题相关依赖，示例如下：

  sphinx>=4.0.0
  sphinx-rtd-theme>=1.0.0
  myst-parser==0.18.1
  

  RTD不会自动安装基础依赖，必须逐一明确。

• 检查conf.py的扩展配置：
  确保extensions列表里是'myst_parser'（使用下划线，而非横杠），示例如下：

  extensions = [
      'sphinx_rtd_theme',
      'myst_parser',
      # 其他用到的扩展
  ]
  

  拼写错误是触发“找不到模块”报错的常见原因。

• 清除RTD缓存并重新构建：
  登录RTD项目页面，进入「Builds」选项卡，点击「Trigger a new build」，选择「Clear cache and build」，强制重新拉取依赖并构建，避免缓存导致的依赖未更新问题。

• 点赞：点击回答左上角的向上箭头按钮，给Steve Piercy的回答投赞成票；
• 接受答案：如果该回答解决了你的问题，点击回答旁的复选框（标注「Accept answer」），将其设为已接受答案，这是对回答者最直接的认可；
• 可选操作：可在回答的评论区回复感谢，表达谢意。

内容的提问来源于stack exchange，提问作者user1255603