Read the Docs项目构建流程优化：默认Sphinx/MkDocs步骤的调整方案

作为文档托管领域的标杆项目，Read the Docs近期正在对其构建系统进行重要升级。技术团队发现当前构建流程中存在一个关键问题需要解决：当用户通过新引入的build.jobs.builds配置自定义构建步骤时，系统仍会默认执行Sphinx/MkDocs的标准构建流程，这可能导致重复操作或冲突。

现状分析

在现有架构中，Read the Docs默认采用以下行为逻辑：

1. 当项目未明确指定构建工具时，系统自动回退到Sphinx构建器
2. 即使用户通过新配置定义了完整的构建流程，系统仍会叠加执行默认步骤

这种设计源于历史兼容性考虑，但随着配置系统的演进，特别是引入build.jobs.builds等高级功能后，这种隐式行为开始显现出局限性。

技术挑战

核心矛盾点在于：

• 向后兼容需求：少量旧项目依赖这种隐式Sphinx构建逻辑
• 功能演进需求：新配置系统需要更精确的构建流程控制

技术团队经过深入讨论，提出了几个关键认知：

1. 隐式构建逻辑应当逐步淘汰，最终要求显式声明构建工具
2. 新配置系统的优先级应高于传统默认行为
3. 过渡期需要平衡创新与稳定的关系

解决方案

经过技术论证，团队确定了分阶段实施路径：

短期方案（立即生效）

• 当检测到用户配置中包含build.jobs.builds定义时
• 且未显式声明sphinx或mkdocs配置项时
• 系统将跳过所有默认构建步骤

这种启发式判断能在不破坏现有项目的前提下，为高级用户提供更灵活的构建控制。

中期规划（1-2个月）

1. 正式公告隐式构建逻辑的弃用计划
2. 为受影响项目提供迁移指南
3. 在文档和日志中添加显式警告

长期目标

• 将sphinx/mkdocs配置项设为必填项
• 完全移除隐式构建逻辑
• 建立更清晰的构建流程定义规范

技术影响评估

这一变更主要影响以下场景：

1. 使用自定义构建流程但未声明构建工具的项目
   • 解决方案：显式添加sphinx: {}或等效配置
2. 依赖隐式Sphinx行为的传统项目
   • 过渡期内仍可工作，但会收到迁移提示
3. 新创建的项目
   • 必须明确指定构建工具，符合显式优于隐式的设计原则

最佳实践建议

对于不同用户群体，我们推荐：

• 新项目：始终在配置中明确声明构建工具
• 现有项目：
  • 如果使用自定义构建：添加空sphinx/mkdocs声明
  • 如果依赖默认行为：尽快添加显式配置
• 插件开发者：适配新的显式配置模式

技术实现要点

在实现层面，核心修改将包括：

1. 构建流程决策逻辑重构
2. 配置验证机制增强
3. 弃用警告系统集成
4. 文档和错误提示更新

这种渐进式改进方案既满足了新功能的需求，又为传统用户提供了合理的过渡期，体现了Read the Docs项目对稳定性和创新性的平衡追求。