diff --git a/doc/conf.py b/doc/conf.py index aad73e59bca..2de3f34aa2e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -4,8 +4,16 @@ import os import re import time +from typing import TYPE_CHECKING -from sphinx import __display_version__ +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 os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1' @@ -254,13 +262,10 @@ # -- Extension interface ------------------------------------------------------- -from sphinx import addnodes # NoQA: E402 -from sphinx.application import Sphinx # NoQA: E402, TCH001 - _event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)') -def parse_event(env, sig, signode): +def parse_event(_env: BuildEnvironment, sig: str, signode: nodes.Element) -> str: m = _event_sig_re.match(sig) if m is None: signode += addnodes.desc_name(sig, sig) @@ -275,11 +280,13 @@ def parse_event(env, sig, signode): return name -def linkify_issues_in_changelog(app, path, docname, source): +def linkify_issues_in_changelog( + _app: Sphinx, _path: Path, docname: str, source: list[str] +) -> None: """Linkify issue references like #123 in changelog to GitHub.""" if docname == 'changes': - def linkify(match): + def linkify(match: re.Match[str]) -> str: url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1] return f'`{match[0]} <{url}>`_' @@ -338,7 +345,7 @@ def setup(app: Sphinx) -> None: app.connect('include-read', linkify_issues_in_changelog) app.connect('build-finished', build_redirects) fdesc = GroupedField( - 'parameter', label='Parameters', names=['param'], can_collapse=True + 'parameter', label='Parameters', names=('param',), can_collapse=True ) app.add_object_type( 'event', diff --git a/pyproject.toml b/pyproject.toml index 96aa09271e8..4348960dbc2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -135,7 +135,7 @@ exclude = [ ] [tool.mypy] -files = ["sphinx", "utils", "tests"] +files = ["sphinx", "utils", "tests", "doc/conf.py"] exclude = [ "tests/roots", # tests/ diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 28559e0eccc..63ec1a0e8f8 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 | None = None) -> Callable: +def cut_lines(pre: int, post: int = 0, what: str | list[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.