ReadTheDocs构建时执行python env create而非conda env create的问题及解决方法

看起来你的问题是因为配置文件中同时存在python.install和conda.environment块，导致ReadTheDocs的构建逻辑混淆，错误地执行了python env create而非conda create命令。下面是具体的解决方案：

核心原因 #

当你同时配置了python.install（pip依赖安装）和conda.environment（conda环境管理）时，ReadTheDocs的构建流程可能优先触发pip相关的逻辑，从而忽略了conda环境的正确创建步骤，进而出现命令错误。

解决方案步骤 #

1. 移除冲突的python.install配置块 #

如果你的项目依赖完全通过environment.yml管理（包括构建文档所需的依赖，比如Sphinx），直接删除配置中的python部分即可。因为conda环境会自动处理所有依赖的安装，不需要额外的pip配置。

修改后的.readthedocs.yaml配置如下：

# .readthedocs.yaml
# Read the Docs configuration file
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-20.04
  tools:
    python: "3.9"

# Build documentation in the docs/ directory with Sphinx
sphinx:
  builder: html
  configuration: docs/source/conf.py
  fail_on_warning: true

# 仅保留conda环境配置，移除python.install部分
conda:
  environment: environment.yml

2. 调整environment.yml的内容（可选但推荐） #

确保你的environment.yml不要包含自定义的name字段——ReadTheDocs会自动为构建环境分配名称（比如develop），自定义名称可能导致冲突。示例的正确environment.yml内容：

dependencies:
  - python=3.9
  - sphinx
  - sphinx-rtd-theme  # 示例：文档主题依赖
  - pip
  - pip:
      - some-pip-only-package  # 如果有仅通过pip安装的依赖

3. 验证依赖完整性 #

确认environment.yml中包含了所有构建文档需要的依赖（比如Sphinx、相关扩展包等），这样conda创建环境后就能直接用于文档构建，不需要额外的pip安装步骤。

原理说明 #

当你只保留conda.environment配置时，ReadTheDocs会自动识别这是一个conda环境构建任务，转而执行正确的conda create --quiet --name develop --file environment.yml命令，而不会错误调用python的env子命令。

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