ReadtheDocs构建报错Sphinx version error，依赖固定仍异常

问题核心 #

dask-image项目PR#344的文档构建抛出Sphinx version error，日志显示使用了Sphinx v4.5.0，但项目已通过continuous_integration/environment-doc.yml固定Sphinx版本≥5，且该环境文件未做改动，ReadtheDocs后台却自动添加了低版本的Sphinx依赖。

原因分析 #

ReadtheDocs自带默认依赖自动检测机制：当检测到项目存在Sphinx配置文件（如conf.py）时，会自动向构建环境添加Sphinx依赖，且默认使用较旧的稳定版本，这会覆盖你在conda环境文件中指定的版本约束。

解决方案 #

1. 配置ReadtheDocs使用自定义conda环境
   在项目根目录创建或修改.readthedocs.yml，明确指定使用自定义环境文件，同时禁用自动依赖安装：

   build:
     os: ubuntu-22.04
     tools:
       python: "3.10"
   # 指定项目的conda环境文件
   conda:
     environment: continuous_integration/environment-doc.yml
   # 禁止ReadtheDocs自动安装Python依赖
   python:
     install: []
   

2. 确认环境文件的版本约束
   检查continuous_integration/environment-doc.yml中Sphinx的版本配置是否正确，例如：

   dependencies:
     - sphinx >=5.0
     # 其他项目依赖...
   

3. 关闭后台自动依赖检测
   进入ReadtheDocs项目后台的「Advanced Settings」页面，找到「Automatic documentation detection」相关选项，关闭自动添加依赖的功能，确保构建完全遵循自定义环境配置。

4. 触发重新构建
   在PR页面手动触发ReadtheDocs重新构建，查看日志确认Sphinx版本已切换至≥5的指定版本。

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