Sphinx 的发布过程¶

版本管理¶

Sphinx遵循 PEP 440 版本规范,采用 major.minor.micro 方案用于 发布部分 （例如 1.2.3）.主要版本、次要版本和微版本部分应按以下方式进行更改:

主要版本部分应在不兼容的行为变化和公共API更新时进行递增.
Sphinx的大多数版本更新中,次版本号应递增,以保持API和功能的向后兼容性.
微版本部分仅应在紧急的仅修复错误的版本中递增.

当主版本部分递增时,次版本和微版本部分必须设置为 0 .当次版本部分递增时,微版本部分必须设置为 0 .

新主要版本在最终发布之前应该经过一个beta测试阶段.

不推荐使用某个特性¶

有几个原因导致Sphinx中的代码可能被弃用:

如果某个功能已经以不兼容的方式进行了改进或修改,则旧功能或行为将被弃用.
有时候,Sphinx会包含一个不在当前支持的Python版本中的库的回溯版本.当Sphinx不再需要支持该旧版本的Python（该版本不包含该库）时,该库将在Sphinx中被弃用.

如 :ref :deprecation-policy 所述,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 将彻底移除此功能.

弃用警告¶

Sphinx将默认启用其 RemovedInNextVersionWarning 警告,前提是未设置:envvar:python:PYTHONWARNINGS .因此,您可以通过以下方式禁用它们:

PYTHONWARNINGS= make html (Linux/Mac)
export PYTHONWARNINGS= and do make html (Linux/Mac)
设置 PYTHONWARNINGS= 并执行 make html （Windows）

但是您也可以显式启用待处理的警告,例如使用 PYTHONWARNINGS=default （有关详细信息,请参见 Python 文档中的配置警告）.

Python 版本支持政策¶

Sphinx支持过去3年内发布的所有小版本的Python,最少支持3个小版本.该政策源自 SPEC 0 ,这是一个科学Python领域标准.

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

这是当前政策的汇总表:

日期	Python
05 10 2023	3.10+
04 10月 2024	3.11+
24 十月 2025	3.12+
01 2026年10月	3.13+
01 2027年10月	3.14+

发布流程¶

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