Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-121277: Allow .. versionadded:: next in docs #121278

Merged
merged 18 commits into from
Sep 25, 2024
Merged
Show file tree
Hide file tree
Changes from 13 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Doc/c-api/long.rst
Original file line number Diff line number Diff line change
Expand Up @@ -511,7 +511,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:: int PyUnstable_Long_IsCompact(const PyLongObject* op)
Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/unicode.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/ast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2485,7 +2485,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:
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/ctypes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/dis.rst
Original file line number Diff line number Diff line change
Expand Up @@ -926,7 +926,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
Expand Down Expand Up @@ -1798,7 +1798,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**
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/pathlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1554,7 +1554,7 @@ Copying, renaming and deleting
extended attributes are copied where supported. This argument has no effect
on Windows, where metadata is always preserved when copying.

.. versionadded:: 3.14
.. versionadded:: next


.. method:: Path.copytree(target, *, follow_symlinks=True, dirs_exist_ok=False, \
Expand All @@ -1581,7 +1581,7 @@ Copying, renaming and deleting
nothing, in which case the copying operation continues. If *on_error* isn't
given, exceptions are propagated to the caller.

.. versionadded:: 3.14
.. versionadded:: next


.. method:: Path.rename(target)
Expand Down
8 changes: 4 additions & 4 deletions Doc/library/symtable.rst
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,7 @@ Examining Symbol Tables

Return ``True`` if the symbol is a type parameter.

.. versionadded:: 3.14
.. versionadded:: next

.. method:: is_global()

Expand Down Expand Up @@ -286,7 +286,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()

Expand All @@ -296,13 +296,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()

Expand Down
24 changes: 22 additions & 2 deletions Doc/tools/extensions/pyspecific.py
Original file line number Diff line number Diff line change
Expand Up @@ -393,7 +393,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
Expand All @@ -404,7 +419,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

Expand Down Expand Up @@ -674,6 +690,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)
Expand Down
79 changes: 79 additions & 0 deletions Doc/tools/version_next.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
#!/usr/bin/env python3
"""
Replace `.. versionchanged:: next` lines in docs files by the given version.

Run this at release time to replace `next` with the just-released version
in the sources.

No backups are made; add/commit to Git before running the script.

Applies to all the VersionChange directives. For deprecated-removed, only
handle the first argument (deprecation version, not the removal version).

AA-Turner marked this conversation as resolved.
Show resolved Hide resolved
"""

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*
AA-Turner marked this conversation as resolved.
Show resolved Hide resolved
)
next
(?P<after>
.*
)
''',
re.VERBOSE | re.DOTALL,
)

docdir = (Path(__file__)
.parent # cpython/Doc/tools
.parent # cpython/Doc
.resolve()
)
encukou marked this conversation as resolved.
Show resolved Hide resolved

parser = argparse.ArgumentParser(
description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument('version',
help='String to replace "next" with.')
encukou marked this conversation as resolved.
Show resolved Hide resolved
parser.add_argument('directory', type=Path, nargs='?',
help=f'Directory to process. Default: {docdir}',
default=docdir)
encukou marked this conversation as resolved.
Show resolved Hide resolved
parser.add_argument('--verbose', '-v', action='count', default=0)
encukou marked this conversation as resolved.
Show resolved Hide resolved

def main(argv):
encukou marked this conversation as resolved.
Show resolved Hide resolved
args = parser.parse_args(argv)
version = args.version
encukou marked this conversation as resolved.
Show resolved Hide resolved
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'):
encukou marked this conversation as resolved.
Show resolved Hide resolved
num_changed_lines = 0
lines = []
with open(path, encoding='utf-8') 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)
encukou marked this conversation as resolved.
Show resolved Hide resolved
with open(path, 'w', encoding='utf-8') 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:])
99 changes: 99 additions & 0 deletions Lib/test/test_tools/test_docs_version_next.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
"""Sanity-check tests for the "docs/replace_versoin_next" tool."""
encukou marked this conversation as resolved.
Show resolved Hide resolved

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')
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Writers of CPython's documentation can now use ``next`` as the version for
the ``versionchanged``, ``versionadded``, ``deprecated`` directives.
Loading