pythongh-121277: Allow .. versionadded:: next in docs (pythonGH-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>
(cherry picked from commit 7d24ea9)

Doc/tools/extensions/pyspecific.py

@@ -259,7 +259,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
@@ -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)

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.