From 1e01dcf429e498ef592b4152b9663fbf263ea54c Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 28 Oct 2024 14:30:29 +0100
Subject: [PATCH] [3.12] gh-121277: Allow `.. versionadded:: next` in docs
 (GH-121278) (GH-125980)

Make `versionchanged:: next`` expand to current (unreleased) version.

When a new CPython release is cut, the release manager will replace
all such occurences of "next" with the just-released version.
(See the issue for release-tools and devguide PRs.)

(cherry picked from commit 7d24ea9db3e8fdca52058629c9ba577aba3d8e5c)

Also backports a minor fix-up:
gh-121277: Raise nice error on `next` as second argument to deprecated-removed (GH-124623)

(cherry-picked from commit e349f73a5ad2856b0a7cbe4aef7cc081c7aed777)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
---
 Doc/tools/extensions/pyspecific.py            | 27 +++++++++++++++++--
 ...-07-19-12-22-48.gh-issue-121277.wF_zKd.rst |  2 ++
 2 files changed, 27 insertions(+), 2 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2024-07-19-12-22-48.gh-issue-121277.wF_zKd.rst

diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 8cb5eaffebfad0..615c7f1f30fc6c 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -184,7 +184,22 @@ def run(self):
         return PyMethod.run(self)
 
 
-# Support for documenting version of removal in deprecations
+# Support for documenting version of changes, additions, deprecations
+
+def expand_version_arg(argument, release):
+    """Expand "next" to the current version"""
+    if argument == 'next':
+        return sphinx_gettext('{} (unreleased)').format(release)
+    return argument
+
+
+class PyVersionChange(VersionChange):
+    def run(self):
+        # Replace the 'next' special token with the current development version
+        self.arguments[0] = expand_version_arg(self.arguments[0],
+                                               self.config.release)
+        return super().run()
+
 
 class DeprecatedRemoved(VersionChange):
     required_arguments = 2
@@ -195,8 +210,12 @@ class DeprecatedRemoved(VersionChange):
     def run(self):
         # Replace the first two arguments (deprecated version and removed version)
         # with a single tuple of both versions.
-        version_deprecated = self.arguments[0]
+        version_deprecated = expand_version_arg(self.arguments[0],
+                                                self.config.release)
         version_removed = self.arguments.pop(1)
+        if version_removed == 'next':
+            raise ValueError(
+                'deprecated-removed:: second argument cannot be `next`')
         self.arguments[0] = version_deprecated, version_removed
 
         # Set the label based on if we have reached the removal version
@@ -398,6 +417,10 @@ def setup(app):
     app.add_role('issue', issue_role)
     app.add_role('gh', gh_issue_role)
     app.add_directive('impl-detail', ImplementationDetail)
+    app.add_directive('versionadded', PyVersionChange, override=True)
+    app.add_directive('versionchanged', PyVersionChange, override=True)
+    app.add_directive('versionremoved', PyVersionChange, override=True)
+    app.add_directive('deprecated', PyVersionChange, override=True)
     app.add_directive('deprecated-removed', DeprecatedRemoved)
     app.add_builder(PydocTopicsBuilder)
     app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature)
diff --git a/Misc/NEWS.d/next/Documentation/2024-07-19-12-22-48.gh-issue-121277.wF_zKd.rst b/Misc/NEWS.d/next/Documentation/2024-07-19-12-22-48.gh-issue-121277.wF_zKd.rst
new file mode 100644
index 00000000000000..60f75ae0c21326
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2024-07-19-12-22-48.gh-issue-121277.wF_zKd.rst
@@ -0,0 +1,2 @@
+Writers of CPython's documentation can now use ``next`` as the version for
+the ``versionchanged``, ``versionadded``, ``deprecated`` directives.