diff --git a/doc/conf.py b/doc/conf.py index da753aa9c66..6980eb91595 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -6,14 +6,7 @@ import time from typing import TYPE_CHECKING -from sphinx import __display_version__, addnodes -from sphinx.application import Sphinx -from sphinx.environment import BuildEnvironment - -if TYPE_CHECKING: - from pathlib import Path - - from docutils import nodes +from sphinx import __display_version__ os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1' @@ -263,10 +256,20 @@ # -- Extension interface ------------------------------------------------------- +from sphinx import addnodes # NoQA: E402 + +if TYPE_CHECKING: + from pathlib import Path + + from docutils.nodes import Element + + from sphinx.application import Sphinx + from sphinx.environment import BuildEnvironment + _event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)') -def parse_event(_env: BuildEnvironment, sig: str, signode: nodes.Element) -> str: +def parse_event(_env: BuildEnvironment, sig: str, signode: Element) -> str: m = _event_sig_re.match(sig) if m is None: signode += addnodes.desc_name(sig, sig) diff --git a/pyproject.toml b/pyproject.toml index f9202d8e839..9e00b59c2ac 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -137,7 +137,12 @@ exclude = [ ] [tool.mypy] -files = ["sphinx", "utils", "tests", "doc/conf.py"] +files = [ + "doc/conf.py", + "sphinx", + "tests", + "utils", +] exclude = [ "tests/roots", # tests/ diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 63ec1a0e8f8..4f6e776d656 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -177,7 +177,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) -> Callable: +def cut_lines(pre: int, post: int = 0, what: Sequence[str] | None = None) -> Callable: """Return a listener that removes the first *pre* and last *post* lines of every docstring. If *what* is a sequence of strings, only docstrings of a type in *what* will be processed. @@ -185,13 +185,15 @@ def cut_lines(pre: int, post: int = 0, what: str | list[str] | None = None) -> C Use like this (e.g. in the ``setup()`` function of :file:`conf.py`):: from sphinx.ext.autodoc import cut_lines - app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) + app.connect('autodoc-process-docstring', cut_lines(4, what={'module'})) This can (and should) be used in place of :confval:`automodule_skip_lines`. """ + what_unique = frozenset(what or ()) + def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: list[str], ) -> None: - if what and what_ not in what: + if what_ not in what_unique: return del lines[:pre] if post: