Read the Docs（RTD）是否提供conf.py配置文件官方说明文档？

现有配置触发构建失败的原因 #

你列出的三个配置项和RTD平台的默认构建逻辑存在冲突，具体问题如下：

• html_theme = 'sphinx_rtd_theme'：RTD平台默认会自动注入定制化版本的sphinx_rtd_theme，手动指定该主题会覆盖平台的定制修改，打断预设的构建链路
• html_context = { 'css_files': ['_static/css/theme_overrides.css', ]}：RTD会通过html_context字段注入平台运行必需的CSS、JS资源，直接重写该字段会导致平台资源丢失，直接触发构建失败。如果需要添加自定义样式，可替换为Sphinx原生的html_css_files配置，该字段不会覆盖平台原有注入内容
• templates_path = ['../templates']：RTD构建环境的工作目录和本地环境不一致，向上回溯的相对路径会导致构建时找不到指定模板目录，引发路径错误。建议改为基于conf.py位置构造的绝对路径，示例如下：

import os
templates_path = [os.path.join(os.path.abspath(os.path.dirname(__file__)), '../templates')]

如果需要同时兼容本地构建和RTD平台构建，可以添加环境判断逻辑，仅在本地运行时加载可能和RTD冲突的配置。

conf.py 配置规则说明 #

目前RTD没有公开的conf.py配置项黑白名单清单，但是遵循以下规则即可避免绝大多数构建冲突：

• 不要直接重写html_context字段，如果需要扩展该字段，先读取原有值再追加自定义内容
• 不要在RTD构建环境中手动指定html_theme为sphinx_rtd_theme，平台会自动完成主题配置
• 所有路径类配置优先使用绝对路径，避免依赖工作目录的相对路径
• 项目根目录添加requirements.txt文件，指定和本地一致的Sphinx及相关依赖版本，避免版本差异导致的配置不兼容问题

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