Sphinx 的发布流程¶

版本控制¶

Sphinx 遵循 PEP 440 版本规范，使用 major.minor.micro 方案表示发布段（例如 1.2.3）。主版本、次版本和修订版本部分应按如下方式更改

当主版本部分递增时，次版本和修订版本部分必须设置为 0。当次版本部分递增时，修订版本部分必须设置为 0。

新的主版本在最终发布之前应有一段 Beta 测试期。

Sphinx 中的代码可能由于以下几个原因而被弃用

如果某个特性以不兼容的方式进行了改进或修改，则旧的特性或行为将被弃用。
有时，Sphinx 会包含某个 Python 库的反向移植版本，而该库未包含在 Sphinx 当前支持的 Python 版本中。当 Sphinx 不再需要支持不包含该库的旧版 Python 时，该库将在 Sphinx 中被弃用。

如弃用策略所述，第一个弃用某个特性的 Sphinx 版本（A.B）在调用该弃用特性时应该抛出 RemovedInSphinxXXWarning（其中 XX 是该特性将被移除的 Sphinx 版本）。假设我们有良好的测试覆盖率，这些警告在使用启用了警告的测试套件运行时会被转换为错误。

pytest -Wall

因此，在添加 RemovedInSphinxXXWarning 时，需要消除或屏蔽运行测试时生成的任何警告。

主版本和次版本发布可能会弃用先前版本中的某些特性。如果某个特性在 A.x 版本中被弃用，它将在所有 A.x.x 版本（对于所有 x 版本）中继续工作。它将在所有 B.x.x 版本中继续工作，但会发出弃用警告。弃用的特性将在 C.0.0 版本中移除。这意味着弃用的特性至少会在 2 个主版本期间有效。

例如，如果我们决定从 Sphinx 2.x 开始弃用某个函数

Sphinx 2.x 将包含该函数的向后兼容副本，该副本将抛出 RemovedInSphinx40Warning。这是 PendingDeprecationWarning 的子类，即默认情况下不会显示。
Sphinx 3.x 仍将包含向后兼容副本，但 RemovedInSphinx40Warning 将成为 DeprecationWarning 的子类，然后默认情况下会显示。
Sphinx 4.0 将完全移除该特性。

如果未设置 PYTHONWARNINGS，Sphinx 将默认启用其 RemovedInNextVersionWarning 警告。因此，可以使用以下命令禁用它们：

但您也可以使用例如 PYTHONWARNINGS=default 显式启用挂起的警告（请参阅 Python 文档中关于配置警告的部分）以获取更多详细信息。

Sphinx 支持过去 3 年内发布的所有 Python 次版本，从预期的发布日期算起，至少支持 3 个 Python 次版本。此策略源自 SPEC 0，这是一个科学 Python 领域的标准。

例如，2025 年 5 月发布的 Sphinx 版本将支持 Python 3.11、3.12 和 3.13。

以下是当前策略的汇总表

发布流程列在 utils/release-checklist.rst 中。