Read the Docs项目中PyMC文档构建的版本冲突问题分析

问题背景

在Read the Docs平台上构建PyMC项目文档时，遇到了一个奇怪的版本冲突问题。文档构建过程中出现了两个不同版本的PyMC共存的情况，导致文档中的代码示例执行结果不一致。

问题现象

在文档构建完成后，发现：

1. 通过jupyter-sphinx执行的代码示例使用的是预期的开发版本（0+untagged.50.g09fd0d7.dirty）
2. 通过myst-nb执行的笔记本代码却使用了旧版本（5.15.1）
3. 两个版本似乎指向相同的源代码位置，但实际内容却不同

技术分析

环境配置

项目使用了Mamba环境管理工具，配置文件中包含：

1. 通过conda/mamba安装依赖项
2. 通过pip install .安装当前开发版本的PyMC
3. 创建了专门的Jupyter内核用于文档构建

版本冲突表现

1. 版本号不一致：开发版本与稳定版本共存
2. 函数签名不一致：同一函数在不同位置显示不同参数名（samples vs draws）
3. 源代码不一致：通过inspect模块检查时，同一文件显示不同内容

可能原因

1. 环境隔离不彻底：虽然指定了内核，但可能存在环境变量或路径污染
2. 缓存问题：构建过程中某些组件可能缓存了旧版本
3. 安装顺序问题：依赖解析可能导致意外安装旧版本
4. 文档构建工具差异：jupyter-sphinx和myst-nb可能使用不同的执行环境

解决方案探索

1. 版本硬编码测试：尝试硬编码版本号，确认问题是否与动态版本生成有关
2. 环境清理：确保构建前彻底清理可能存在的旧版本
3. 执行环境验证：增加调试输出，确认代码执行时的实际环境路径
4. 构建工具配置：检查文档构建工具的配置，确保环境一致性

经验总结

1. 在复杂文档项目中，多个代码执行工具并存时需特别注意环境一致性
2. 动态版本生成机制在特定环境下可能产生意外结果
3. 文档构建过程中的隐式依赖和缓存可能引入难以排查的问题
4. 建议在文档构建脚本中加入详细的版本和环境验证步骤

这个问题展示了在持续集成环境中管理Python包版本和文档构建的复杂性，特别是在开发版本和发布版本并存的情况下。通过系统性的环境隔离和验证机制可以有效预防此类问题。