Read the Docs项目中Poetry依赖管理失效问题的解决方案

在Read the Docs文档构建服务中，使用Poetry作为依赖管理工具的项目可能会遇到构建失败的问题。近期有用户反馈，其项目明明在pyproject.toml中指定了Sphinx 4.2版本，但实际构建时却使用了Sphinx 7.2.6版本，导致与现有扩展不兼容。

经过技术分析，这是由于Read the Docs服务近期对Poetry支持机制进行了重要变更。在旧版本中，系统会自动识别pyproject.toml中的依赖配置，但在新版本中需要显式地在.readthedocs.yaml配置文件中声明使用Poetry安装依赖。

具体表现为：

1. 构建过程忽略pyproject.toml中的依赖声明
2. 自动使用最新版本的构建工具（如Sphinx）
3. 导致与项目中指定的扩展版本不兼容

解决方案很简单：需要在项目的.readthedocs.yaml配置文件中明确添加Poetry安装指令。更新后的配置应该包含使用Poetry安装依赖的步骤，确保构建环境能够正确识别项目指定的所有依赖版本。

这个问题特别值得Python项目维护者注意，尤其是：

1. 使用Poetry作为包管理工具的项目
2. 对文档构建工具版本有特定要求的项目
3. 依赖特定版本扩展的文档项目

通过正确配置.readthedocs.yaml文件，可以确保文档构建过程使用项目指定的确切依赖版本，避免因版本冲突导致的构建失败。这也体现了现代Python项目依赖管理的重要性，特别是在持续集成环境中。

对于遇到类似问题的开发者，建议首先检查构建日志确认实际使用的依赖版本，然后核对配置文件是否符合最新规范。这种主动依赖管理方式不仅能解决当前问题，还能提高项目构建的可预测性和稳定性。