IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Restore support for `cut_lines()` with no object type (#13015)

Browse Source
This commit is contained in:
Adam Turner 2024-10-12 23:14:24 +01:00 committed by GitHub
parent 5ae32ce9bf
commit 62e9606d63
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 30 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGES.rst
View File

@ -4,6 +4,8 @@ Release 8.1.3 (in development)
Bugs fixed 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) Release 8.1.2 (released Oct 12, 2024)
===================================== =====================================

11
sphinx/ext/autodoc/__init__.py
View File

@ -186,7 +186,7 @@ def merge_members_option(options: dict) -> None:
# Some useful event listener factories for autodoc-process-docstring. # Some useful event listener factories for autodoc-process-docstring.
def cut_lines( 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: ) -> _AutodocProcessDocstringListener:
"""Return a listener that removes the first *pre* and last *post* """Return a listener that removes the first *pre* and last *post*
lines of every docstring. If *what* is a sequence of strings, 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`. 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( def process(
app: Sphinx, app: Sphinx,
@ -209,7 +214,7 @@ def cut_lines(
options: dict[str, bool], options: dict[str, bool],
lines: list[str], lines: list[str],
) -> None: ) -> None:
if what_ not in what_unique: if what_unique and what_ not in what_unique:
return return
del lines[:pre] del lines[:pre]
if post: if post:

20
tests/test_extensions/test_ext_autodoc_events.py
View File

@ -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') @pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_between(app): def test_between(app):
app.connect('autodoc-process-docstring', between('---', ['function'])) app.connect('autodoc-process-docstring', between('---', ['function']))