gh-121277: Allow `.. versionadded:: next` in docs (GH-121278)

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.)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

9 files changed, 36 insertions, 14 deletions

diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 098a55c..188eec4 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -570,7 +570,7 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    On failure, return -1 with an exception set.  This function always succeeds
    if *obj* is a :c:type:`PyLongObject` or its subtype.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. c:function:: PyObject* PyLong_GetInfo(void)
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 958fafd..30e26fe 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -1534,7 +1534,7 @@ PyUnicodeWriter
 The :c:type:`PyUnicodeWriter` API can be used to create a Python :class:`str`
 object.
 
-.. versionadded:: 3.14
+.. versionadded:: next
 
 .. c:type:: PyUnicodeWriter
 
diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index 5500762..a8a18ad 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -2491,7 +2491,7 @@ effects on the compilation of a program:
    differ in whitespace or similar details. Attributes include line numbers
    and column offsets.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. _ast-cli:
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index a218304..535c517 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -2303,7 +2303,7 @@ These are the fundamental ctypes data types:
    Represents the C :c:expr:`double complex` datatype, if available.  The
    constructor accepts an optional :class:`complex` initializer.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. class:: c_float_complex
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 662c890..e3919c2 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -959,7 +959,7 @@ iterations of the loop.
    list of constants supported by this instruction.  Used by the :keyword:`assert`
    statement to load :exc:`AssertionError`.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. opcode:: LOAD_BUILD_CLASS
@@ -1826,7 +1826,7 @@ iterations of the loop.
    If ``type(STACK[-1]).__xxx__`` is not a method, leave
    ``STACK[-1].__xxx__; NULL`` on the stack.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 **Pseudo-instructions**
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 4380122..30d0d38 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1563,7 +1563,7 @@ Copying, moving and deleting
    This argument has no effect when copying files on Windows (where
    metadata is always preserved).
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. method:: Path.copy_into(target_dir, *, follow_symlinks=True, \
@@ -1574,7 +1574,7 @@ Copying, moving and deleting
    :meth:`Path.copy`. Returns a new :class:`!Path` instance pointing to the
    copy.
 
-   .. versionadded:: 3.14
+   .. versionadded:: next
 
 
 .. method:: Path.rename(target)
diff --git a/Doc/library/symtable.rst b/Doc/library/symtable.rst
index 8ebcb3b..15e0b23 100644
--- a/Doc/library/symtable.rst
+++ b/Doc/library/symtable.rst
@@ -255,7 +255,7 @@ Examining Symbol Tables
 
       Return ``True`` if the symbol is a type parameter.
 
-      .. versionadded:: 3.14
+      .. versionadded:: next
 
    .. method:: is_global()
 
@@ -302,7 +302,7 @@ Examining Symbol Tables
       be free from the perspective of ``C.method``, thereby allowing
       the latter to return *1* at runtime and not *2*.
 
-      .. versionadded:: 3.14
+      .. versionadded:: next
 
    .. method:: is_assigned()
 
@@ -312,13 +312,13 @@ Examining Symbol Tables
 
       Return ``True`` if the symbol is a comprehension iteration variable.
 
-      .. versionadded:: 3.14
+      .. versionadded:: next
 
    .. method:: is_comp_cell()
 
       Return ``True`` if the symbol is a cell in an inlined comprehension.
 
-      .. versionadded:: 3.14
+      .. versionadded:: next
 
    .. method:: is_namespace()
 
diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 791d929..1f725c2 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -259,7 +259,22 @@ class PyAbstractMethod(PyMethod):
         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
@@ -270,7 +285,8 @@ 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)
         self.arguments[0] = version_deprecated, version_removed
 
@@ -474,6 +490,10 @@ def setup(app):
     app.add_role('gh', gh_issue_role)
     app.add_directive('impl-detail', ImplementationDetail)
     app.add_directive('availability', Availability)
+    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 0000000..60f75ae
--- /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.