diff --git a/CHANGES.rst b/CHANGES.rst index 6790e176586..120a2c0c00f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,3 +1,12 @@ +Release 8.1.3 (released Oct 13, 2024) +===================================== + +Bugs fixed +---------- + +* #13013: Restore support for :func:`!cut_lines` with no object type. + Patch by Adam Turner. + Release 8.1.2 (released Oct 12, 2024) ===================================== @@ -24,7 +33,6 @@ Bugs fixed ``fontawesome`` or ``fontawesome5`` packages are not installed. Patch by Jean-François B. - Release 8.1.0 (released Oct 10, 2024) ===================================== diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 524a08b6f4a..0b53226e7f9 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -1,6 +1,6 @@ """The Sphinx documentation toolchain.""" -__version__ = '8.1.2' +__version__ = '8.1.3' __display_version__ = __version__ # used for command line version # Keep this file executable as-is in Python 3! @@ -30,7 +30,7 @@ #: #: .. versionadded:: 1.2 #: Before version 1.2, check the string ``sphinx.__version__``. -version_info = (8, 1, 2, 'final', 0) +version_info = (8, 1, 3, 'final', 0) package_dir = os.path.abspath(os.path.dirname(__file__)) diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index f2c1ed93782..a655dbf5a79 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -186,7 +186,7 @@ def merge_members_option(options: dict) -> None: # Some useful event listener factories for autodoc-process-docstring. def cut_lines( - pre: int, post: int = 0, what: str | list[str] | None = None + pre: int, post: int = 0, what: Sequence[str] | None = None ) -> _AutodocProcessDocstringListener: """Return a listener that removes the first *pre* and last *post* lines of every docstring. If *what* is a sequence of strings, @@ -199,7 +199,12 @@ def cut_lines( This can (and should) be used in place of :confval:`automodule_skip_lines`. """ - what_unique = frozenset(what or ()) + if not what: + what_unique: frozenset[str] = frozenset() + elif isinstance(what, str): # strongly discouraged + what_unique = frozenset({what}) + else: + what_unique = frozenset(what) def process( app: Sphinx, @@ -209,7 +214,7 @@ def process( options: dict[str, bool], lines: list[str], ) -> None: - if what_ not in what_unique: + if what_unique and what_ not in what_unique: return del lines[:pre] if post: diff --git a/tests/test_extensions/test_ext_autodoc_events.py b/tests/test_extensions/test_ext_autodoc_events.py index 733b0be337b..83f2436966f 100644 --- a/tests/test_extensions/test_ext_autodoc_events.py +++ b/tests/test_extensions/test_ext_autodoc_events.py @@ -58,6 +58,26 @@ def test_cut_lines(app): ] +def test_cut_lines_no_objtype(): + docstring_lines = [ + 'first line', + '---', + 'second line', + '---', + 'third line ', + '', + ] + process = cut_lines(2) + + process(None, 'function', 'func', None, {}, docstring_lines) # type: ignore[arg-type] + assert docstring_lines == [ + 'second line', + '---', + 'third line ', + '', + ] + + @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_between(app): app.connect('autodoc-process-docstring', between('---', ['function']))