如何解决Read the Docs无法识别GitHub根目录配置文件的问题？

1. 校验 .readthedocs.yaml 的语法正确性 #

Read the Docs对YAML语法容错率极低，缩进错误、引号不匹配、键名拼写错都会导致配置文件无法被识别。可以用本地工具快速校验：

pip install yamllint
yamllint .readthedocs.yaml

根据输出修正所有语法问题，比如把缩进统一为2个空格、修正拼写错误的键名（比如把verison改成version）。

2. 核对配置文件的命名与路径 #

• 文件名必须是 .readthedocs.yaml，不能少开头的点，也不能写成.readthedocs.yml或者readthedocs.yaml
• 直接在GitHub仓库首页确认文件在根目录，不是嵌套在docs或其他子文件夹里

3. 检查Read the Docs的分支构建设置 #

如果是切换分支后出现的问题：

• 进入Read the Docs项目的「版本」选项卡，确认当前构建的分支（比如main/master）确实包含这个配置文件
• 新分支需要手动添加并启用构建权限

4. 清除缓存后重新构建 #

Read the Docs可能缓存了旧的项目结构，导致新配置文件不被识别：

• 进入项目的「构建」页面，找到最近的失败任务
• 点击「重新构建」，勾选「清除缓存」选项后再执行构建

5. 更新配置文件到当前规范 #

旧版配置语法可能已被废弃，比如早期的python:块结构需要调整。以下是一个符合当前要求的基础模板，可对照调整你的配置：

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.10"

sphinx:
  configuration: docs/conf.py

python:
  install:
    - requirements: docs/requirements.txt

确保version字段是当前支持的版本（比如2），sphinx.configuration正确指向你的文档配置文件路径。

6. 确认GitHub仓库的授权权限 #

Read the Docs需要能读取仓库根目录的权限：

• 检查Read the Docs的GitHub应用是否已授权访问该仓库
• 私有仓库需在Read the Docs中配置对应的访问凭证

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