Type-hints: update to pass mypy checks with types-docutils 0.21.0.20240704

sphinx/ext/autodoc/directive.py

@@ -112,7 +112,7 @@ def run(self) -> list[Node]:
         reporter = self.state.document.reporter
 
         try:
-            source, lineno = reporter.get_source_and_line(
+            source, lineno = reporter.get_source_and_line(  # type: ignore[attr-defined]
                 self.lineno)
         except AttributeError:
             source, lineno = (None, None)

sphinx/ext/inheritance_diagram.py

@@ -378,15 +378,15 @@ def run(self) -> list[Node]:
                 aliases=self.config.inheritance_alias,
                 top_classes=node['top-classes'])
         except InheritanceException as err:
-            return [node.document.reporter.warning(err, line=self.lineno)]  # type: ignore[union-attr]
+            return [node.document.reporter.warning(err, line=self.lineno)]
 
         # Create xref nodes for each target of the graph's image map and
         # add them to the doc tree so that Sphinx can resolve the
         # references to real URLs later.  These nodes will eventually be
         # removed from the doctree after we're done with them.
         for name in graph.get_all_class_names():
             refnodes, x = class_role(  # type: ignore[call-arg,misc]
-                'class', ':class:`%s`' % name, name, 0, self.state)
+                'class', ':class:`%s`' % name, name, 0, self.state.inliner)
             node.extend(refnodes)
         # Store the graph object so we can use it to generate the
         # dot file later

sphinx/util/nodes.py

@@ -325,7 +325,10 @@ def traverse_translatable_index(
         yield node, entries
 
 
-def nested_parse_with_titles(state: RSTState, content: StringList, node: Node,
+_RSTContext = TypeVar("_RSTContext")
+
+
+def nested_parse_with_titles(state: RSTState[_RSTContext], content: StringList, node: Node,
                              content_offset: int = 0) -> str:
     """Version of state.nested_parse() that allows titles and does not require
     titles to have the same decoration as the calling document.

sphinx/util/parsing.py

@@ -3,19 +3,22 @@
 from __future__ import annotations
 
 import contextlib
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from docutils.nodes import Element, Node
 from docutils.statemachine import StringList, string2lines
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
+    # TODO(py312+):
+    # Attempt to improve on 'Any' generic type-arg, perhaps using the 'type' stmt
+    # Ref: https://github.com/sphinx-doc/sphinx/issues/10785#issuecomment-1897551241
     from docutils.parsers.rst.states import RSTState
 
 
 def nested_parse_to_nodes(
-    state: RSTState,
+    state: RSTState[Any],
     text: str | StringList,
     *,
     source: str = '<generated text>',
@@ -67,7 +70,7 @@ def nested_parse_to_nodes(
 
 
 @contextlib.contextmanager
-def _fresh_title_style_context(state: RSTState) -> Iterator[None]:
+def _fresh_title_style_context(state: RSTState[Any]) -> Iterator[None]:
     # hack around title style bookkeeping
     memo = state.memo
     surrounding_title_styles: list[str | tuple[str, str]] = memo.title_styles

tests/test_util/test_util_docutils_sphinx_directive.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from types import SimpleNamespace
+from typing import Any
 
 from docutils import nodes
 from docutils.parsers.rst.languages import en as english  # type: ignore[attr-defined]
@@ -11,16 +12,16 @@
 
 
 def make_directive(*, env: SimpleNamespace, input_lines: StringList | None = None) -> SphinxDirective:
-    state, directive = make_directive_and_state(env=env, input_lines=input_lines)
+    _, directive = make_directive_and_state(env=env, input_lines=input_lines)
     return directive
 
 
-def make_directive_and_state(*, env: SimpleNamespace, input_lines: StringList | None = None) -> tuple[RSTState, SphinxDirective]:
+def make_directive_and_state(*, env: SimpleNamespace, input_lines: StringList | None = None) -> tuple[RSTState[Any], SphinxDirective]:
     sm = RSTStateMachine(state_classes, initial_state='Body')
     sm.reporter = object()
     if input_lines is not None:
         sm.input_lines = input_lines
-    state = RSTState(sm)
+    state: RSTState[Any] = RSTState(sm)
     state.document = new_document('<tests>')
     state.document.settings.env = env
     state.document.settings.tab_width = 4