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。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 中。