Sphinx的释放过程¶

版本化¶

Sphinx坚持 PEP 440 版本，带有 major.minor.micro 计划，为 release segment (例如1.2.3)。主要版本、次要版本和微型版本部分应更改如下：

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

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

Sphinx中的代码可能会被弃用，原因有几个：

如果以向后不兼容的方式改进或修改了某个功能，则旧的功能或行为将被弃用。
有时，Sphinx会包含一个不包含在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中删除。这意味着至少在两个主要版本中，不推荐使用的功能都会起作用。

因此，例如，如果我们决定在Sphinx 2.x中开始弃用一个函数：

Sphinx 2.x将包含该函数的向后兼容副本，这将引发 RemovedInSphinx40Warning 。这是的子类 PendingDeprecationWarning 即，默认情况下不会显示。
Sphinx 3.x仍将包含向后兼容的副本，但 RemovedInSphinx40Warning 将是的子类 DeprecationWarning 然后，默认情况下会显示和。
Sphinx 4.0将彻底删除该功能。

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

但您也可以使用例如，显式启用挂起的。 PYTHONWARNINGS=default (请参阅 Python docs on configuring warnings )了解更多详细信息。

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

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

这是包含当前策略的汇总表：

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