ReadtheDocs文档构建失败：sphinx.output_dir配置异常求助

问题情况 #

在ReadtheDocs构建文档时出现配置冲突：

• 开启.readthedocs.yaml中的sphinx.output_dir配置时，构建报错：Error Make sure the key name \sphinx.output_dir` is correct.`
• 注释该配置后，又报错：Error Some files were detected in an unsupported output path: \_build/html`. Ensure your project is configured to use the output path `$READTHEDOCS_OUTPUT/html``
  本地构建一切正常，仅ReadtheDocs远程构建出现问题。

当前配置文件 #

version: 2

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

sphinx:
  configuration: conf.py
  output_dir: $READTHEDOCS_OUTPUT/html

formats:
  - pdf
  - epub
  - htmlzip

python:
  install:
    - requirements: requirements.txt

解决方案 #

步骤1：修正.readthedocs.yaml配置 #

移除sphinx节点下的output_dir项，修正后的配置如下：

version: 2

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

sphinx:
  configuration: conf.py

formats:
  - pdf
  - epub
  - htmlzip

python:
  install:
    - requirements: requirements.txt

步骤2：调整Sphinx的conf.py配置 #

在项目根目录的conf.py文件中添加或修改html_output_dir配置，适配ReadtheDocs的输出路径要求：

import os

# 适配ReadtheDocs输出路径，本地构建时自动使用默认的_build/html
html_output_dir = os.path.join(os.environ.get('READTHEDOCS_OUTPUT', '_build'), 'html')

原理说明 #

ReadtheDocs v2版本的配置规范中，已不再支持sphinx.output_dir这个配置项，必须通过Sphinx自身的html_output_dir参数来指定输出目录。通过读取环境变量READTHEDOCS_OUTPUT，可以同时满足远程构建的路径要求和本地构建的默认行为，避免冲突。

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