lint: typecheck docs/conf.py (#12697)

doc/conf.py

@@ -4,8 +4,16 @@ from __future__ import annotations
 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 @@ nitpick_ignore = {
 
 # -- 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',

pyproject.toml

@@ -135,7 +135,7 @@ exclude = [
 ]
 
 [tool.mypy]
-files = ["sphinx", "utils", "tests"]
+files = ["sphinx", "utils", "tests", "doc/conf.py"]
 exclude = [
     "tests/roots",
     # tests/

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.