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

- versionadded, versionchanged, and similar directives expand "next" to e.g. "3.14.0a0 (unreleased)". - A tool is provided for release managers to replace all such occurences of "next" with the given string.
python · encukou · Sep 25, 2024 · Jul 2, 2024 · Jul 2, 2024 · Jul 19, 2024
commit f0005e70efb8c35129938dbae8231ebf47b744f9
@@ -28,6 +28,7 @@
 from sphinx.util.docutils import SphinxDirective
 from sphinx.writers.text import TextWriter, TextTranslator
 from sphinx.util.display import status_iterator
+import sphinx.directives.other
 
 
 ISSUE_URI = 'https://bugs.python.org/issue?@action=redirect&bpo=%s'
@@ -393,7 +394,23 @@ 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, env):
+    """Expand "next" to the current version"""
+    if argument == 'next':
+        return sphinx_gettext('{} (unreleased)').format(env.config.release)
+    return argument
+
+
+class PyVersionChange(sphinx.directives.other.VersionChange):
+    def run(self):
+        env = self.state.document.settings.env
+        self.arguments = (
+            expand_version_arg(self.arguments[0], env),
+            *self.arguments[1:])
+        return super().run()
+
 
 class DeprecatedRemoved(Directive):
     has_content = True
@@ -409,17 +426,18 @@ def run(self):
         node = addnodes.versionmodified()
         node.document = self.state.document
         node['type'] = 'deprecated-removed'
-        version = (self.arguments[0], self.arguments[1])
-        node['version'] = version
         env = self.state.document.settings.env
+        deprecated = expand_version_arg(self.arguments[0], env)
+        version = (deprecated, self.arguments[1])
+        node['version'] = version
         current_version = tuple(int(e) for e in env.config.version.split('.'))
         removed_version = tuple(int(e) for e in self.arguments[1].split('.'))
         if current_version < removed_version:
             label = self._deprecated_label
         else:
             label = self._removed_label
 
-        text = label.format(deprecated=self.arguments[0], removed=self.arguments[1])
+        text = label.format(deprecated=deprecated, removed=self.arguments[1])
         if len(self.arguments) == 3:
             inodes, messages = self.state.inline_text(self.arguments[2],
                                                       self.lineno+1)
@@ -448,7 +466,6 @@ def run(self):
         env.get_domain('changeset').note_changeset(node)
         return [node] + messages
 
-
 # Support for including Misc/NEWS
 
 issue_re = re.compile('(?:[Ii]ssue #|bpo-)([0-9]+)', re.I)
@@ -698,6 +715,10 @@ def setup(app):
     app.add_directive('availability', Availability)
     app.add_directive('audit-event', AuditEvent)
     app.add_directive('audit-event-table', AuditEventListDirective)
+    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/Doc/tools/version_next.py b/Doc/tools/version_next.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""
+Replace `.. versionchanged:: next` lines in docs files by the given version.
+
+Applies to all the VersionChange directives. For deprecated-removed, only
+handle the first argument (deprecation version, not the removal version).
+
+"""
+
+import re
+import sys
+import argparse
+from pathlib import Path
+
+DIRECTIVE_RE = re.compile(
+    r'''
+        (?P<before>
+            \s*\.\.\s+
+            (version(added|changed|removed)|deprecated(-removed)?)
+            \s*::\s*
+        )
+        next
+        (?P<after>
+            .*
+        )
+    ''',
+    re.VERBOSE | re.DOTALL,
+)
+
+basedir = (Path(__file__)
+           .parent  # cpython/Tools/doc
+           .parent  # cpython/Tools
+           .parent  # cpython
+           .resolve()
+           )
+docdir = basedir / 'Doc'
+
+parser = argparse.ArgumentParser(
+    description=__doc__,
+    formatter_class=argparse.RawDescriptionHelpFormatter)
+parser.add_argument('version',
+                    help='String to replace "next" with.')
+parser.add_argument('directory', type=Path, nargs='?',
+                    help=f'Directory to process. Default: {docdir}',
+                    default=docdir)
+parser.add_argument('--verbose', '-v', action='count', default=0)
+
+def main(argv):
+    args = parser.parse_args(argv)
+    version = args.version
+    if args.verbose:
+        print(
+            f'Updating "next" versions in {args.directory} to {version!r}',
+            file=sys.stderr)
+    for path in Path(args.directory).glob('**/*.rst'):
+        num_changed_lines = 0
+        lines = []
+        with open(path) as file:
+            for lineno, line in enumerate(file, start=1):
+                if match := DIRECTIVE_RE.fullmatch(line):
+                    line = match['before'] + version + match['after']
+                    num_changed_lines += 1
+                lines.append(line)
+        if num_changed_lines:
+            if args.verbose:
+                print(f'Updating file {path} ({num_changed_lines} changes)',
+                    file=sys.stderr)
+            with open(path, 'w') as file:
+                file.writelines(lines)
+        else:
+            if args.verbose > 1:
+                print(f'Unchanged file {path}', file=sys.stderr)
+
+
+if __name__ == '__main__':
+    main(sys.argv[1:])
diff --git a/Lib/test/test_tools/test_docs_version_next.py b/Lib/test/test_tools/test_docs_version_next.py
@@ -0,0 +1,99 @@
+"""Sanity-check tests for the "docs/replace_versoin_next" tool."""
+
+from pathlib import Path
+import unittest
+
+from test.test_tools import basepath
+from test.support.import_helper import DirsOnSysPath, import_module
+from test.support import os_helper
+from test import support
+
+print(basepath)
+tooldir = Path(basepath) / 'Doc' / 'tools'
+print(tooldir)
+
+with DirsOnSysPath(str(tooldir)):
+    import sys
+    print(sys.path)
+    version_next = import_module('version_next')
+
+TO_CHANGE = """
+Directives to change
+--------------------
+
+Here, all occurences of NEXT (lowercase) should be changed:
+
+.. versionadded:: next
+
+.. versionchanged:: next
+
+.. deprecated:: next
+
+.. deprecated-removed:: next 4.0
+
+whitespace:
+
+..   versionchanged:: next
+
+.. versionchanged  :: next
+
+    .. versionadded:: next
+
+arguments:
+
+.. versionadded:: next
+    Foo bar
+
+.. versionadded:: next as ``previousname``
+"""
+
+UNCHANGED = """
+Unchanged
+---------
+
+Here, the word "next" should NOT be changed:
+
+.. versionchanged:: NEXT
+
+..versionchanged:: NEXT
+
+... versionchanged:: next
+
+foo .. versionchanged:: next
+
+.. otherdirective:: next
+
+.. VERSIONCHANGED: next
+
+.. deprecated-removed: 3.0 next
+"""
+
+EXPECTED_CHANGED = TO_CHANGE.replace('next', 'VER')
+
+
+class TestVersionNext(unittest.TestCase):
+    maxDiff = len(TO_CHANGE + UNCHANGED) * 10
+
+    def test_freeze_simple_script(self):
+        with os_helper.temp_dir() as testdir:
+            path = Path(testdir)
+            path.joinpath('source.rst').write_text(TO_CHANGE + UNCHANGED)
+            path.joinpath('subdir').mkdir()
+            path.joinpath('subdir/change.rst').write_text(
+                '.. versionadded:: next')
+            path.joinpath('subdir/keep.not-rst').write_text(
+                '.. versionadded:: next')
+            path.joinpath('subdir/keep.rst').write_text(
+                'nothing to see here')
+            args = ['VER', testdir]
+            if support.verbose:
+                args.append('-vv')
+            version_next.main(args)
+            self.assertEqual(path.joinpath('source.rst').read_text(),
+                             EXPECTED_CHANGED + UNCHANGED)
+            self.assertEqual(path.joinpath('subdir/change.rst').read_text(),
+                             '.. versionadded:: VER')
+            self.assertEqual(path.joinpath('subdir/keep.not-rst').read_text(),
+                             '.. versionadded:: next')
+            self.assertEqual(path.joinpath('subdir/keep.rst').read_text(),
+                             'nothing to see here')