Sphinx 的发布流程¶

版本控制¶

Sphinx 遵循 PEP 440 版本，对于发布段（例如 1.2.3），采用 major.minor.micro 方案。主要、次要和微版本部分应按如下方式更改

当主版本部分递增时，次要和微版本部分必须设置为 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 中。