[lint] use types-docutils instead of docutils-stubs for ``doc…

…utils`` type annotations (sphinx-doc#12012)

Co-authored-by: daniel.eades <[email protected]>
Co-authored-by: Bénédikt Tran <[email protected]>

pyproject.toml

@@ -85,7 +85,7 @@ lint = [
     "ruff==0.3.4",
     "mypy==1.9.0",
     "sphinx-lint",
-    "docutils-stubs",
+    "types-docutils",
     "types-requests",
     "pytest>=6.0",
 ]

sphinx/addnodes.py

@@ -16,8 +16,8 @@
 
 # deprecated name -> (object to return, canonical path or empty string)
 _DEPRECATED_OBJECTS = {
-    'meta': (nodes.meta, 'docutils.nodes.meta'),  # type: ignore[attr-defined]
-    'docutils_meta': (nodes.meta, 'docutils.nodes.meta'),  # type: ignore[attr-defined]
+    'meta': (nodes.meta, 'docutils.nodes.meta'),
+    'docutils_meta': (nodes.meta, 'docutils.nodes.meta'),
 }
 
 
@@ -45,7 +45,7 @@ class document(nodes.document):
 
     def set_id(self, node: Element, msgnode: Element | None = None,
                suggested_prefix: str = '') -> str:
-        return super().set_id(node, msgnode, suggested_prefix)  # type: ignore[call-arg]
+        return super().set_id(node, msgnode, suggested_prefix)
 
 
 class translatable(nodes.Node):
@@ -89,7 +89,7 @@ class toctree(nodes.General, nodes.Element, translatable):
 
     def preserve_original_messages(self) -> None:
         # toctree entries
-        rawentries = self.setdefault('rawentries', [])
+        rawentries: list[str] = self.setdefault('rawentries', [])
         for title, _docname in self['entries']:
             if title:
                 rawentries.append(title)

sphinx/builders/__init__.py

@@ -520,7 +520,7 @@ def write_doctree(
         doctree.settings = doctree.settings.copy()
         doctree.settings.warning_stream = None
         doctree.settings.env = None
-        doctree.settings.record_dependencies = None  # type: ignore[assignment]
+        doctree.settings.record_dependencies = None
 
         doctree_filename = path.join(self.doctreedir, docname + '.doctree')
         ensuredir(path.dirname(doctree_filename))

sphinx/builders/gettext.py

@@ -67,7 +67,7 @@ def add(self, msg: str, origin: Element | MsgOrigin) -> None:
         line = origin.line
         if line is None:
             line = -1
-        self.metadata[msg].append((origin.source, line, origin.uid))
+        self.metadata[msg].append((origin.source, line, origin.uid))  # type: ignore[arg-type]
 
     def __iter__(self) -> Generator[Message, None, None]:
         for message in self.messages:

sphinx/builders/html/__init__.py

@@ -53,6 +53,7 @@
     from collections.abc import Iterable, Iterator, Set
 
     from docutils.nodes import Node
+    from docutils.readers import Reader
 
     from sphinx.application import Sphinx
     from sphinx.config import _ConfigRebuild
@@ -200,7 +201,7 @@ def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
         self._js_files: list[_JavaScript] = []
 
         # Cached Publisher for writing doctrees to HTML
-        reader = docutils.readers.doctree.Reader(parser_name='restructuredtext')
+        reader: Reader = docutils.readers.doctree.Reader(parser_name='restructuredtext')
         pub = Publisher(
             reader=reader,
             parser=reader.parser,
@@ -437,7 +438,7 @@ def render_partial(self, node: Node | None) -> dict[str, str]:
         doc.append(node)
         self._publisher.set_source(doc)
         self._publisher.publish()
-        return self._publisher.writer.parts  # type: ignore[union-attr]
+        return self._publisher.writer.parts
 
     def prepare_writing(self, docnames: set[str]) -> None:
         # create the search indexer
@@ -767,7 +768,7 @@ def copy_image_files(self) -> None:
 
     def copy_download_files(self) -> None:
         def to_relpath(f: str) -> str:
-            return relative_path(self.srcdir, f)  # type: ignore[arg-type]
+            return relative_path(self.srcdir, f)
 
         # copy downloadable files
         if self.env.dlfiles:

sphinx/builders/latex/transforms.py

@@ -115,7 +115,7 @@ def get_docname_for_node(self, node: Node) -> str:
                 node = node.parent
 
         try:
-            source = node['source']  # type: ignore[index]
+            source = node['source']
         except TypeError:
             raise ValueError(__('Failed to get a docname!')) from None
         raise ValueError(__('Failed to get a docname '
@@ -523,7 +523,7 @@ def run(self, **kwargs: Any) -> None:
             citations += node
 
         if len(citations) > 0:
-            self.document += citations
+            self.document += citations  # type: ignore[attr-defined]
 
 
 class CitationReferenceTransform(SphinxPostTransform):

sphinx/directives/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, Generic, TypeVar, cast
+from typing import TYPE_CHECKING, ClassVar, Generic, TypeVar, cast
 
 from docutils import nodes
 from docutils.parsers.rst import directives, roles
@@ -55,7 +55,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'no-index': directives.flag,
         'no-index-entry': directives.flag,
         'no-contents-entry': directives.flag,
@@ -296,7 +296,7 @@ def run(self) -> list[Node]:
             # If ``:no-index:`` is set, or there are no ids on the node
             # or any of its children, then just return the index node,
             # as Docutils expects a target node to have at least one id.
-            if node_ids := [node_id for el in node.findall(nodes.Element)
+            if node_ids := [node_id for el in node.findall(nodes.Element)  # type: ignore[var-annotated]
                             for node_id in el.get('ids', ())]:
                 target_node = nodes.target(ids=node_ids)
                 self.set_source_info(target_node)
@@ -320,7 +320,7 @@ def run(self) -> list[Node]:
         role_name = self.arguments[0]
         role, messages = roles.role(role_name, self.state_machine.language,
                                     self.lineno, self.state.reporter)
-        if role:  # type: ignore[truthy-function]
+        if role:
             docutils.register_role('', role)  # type: ignore[arg-type]
             self.env.temp_data['default_role'] = role_name
         else:
@@ -342,7 +342,7 @@ class DefaultDomain(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         domain_name = self.arguments[0].lower()

sphinx/directives/code.py

@@ -3,7 +3,7 @@
 import sys
 import textwrap
 from difflib import unified_diff
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, ClassVar
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -35,7 +35,7 @@ class Highlight(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'force': directives.flag,
         'linenothreshold': directives.positive_int,
     }
@@ -102,7 +102,7 @@ class CodeBlock(SphinxDirective):
     required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = False
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'force': directives.flag,
         'linenos': directives.flag,
         'dedent': optional_int,
@@ -393,7 +393,7 @@ class LiteralInclude(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'dedent': optional_int,
         'linenos': directives.flag,
         'lineno-start': int,

sphinx/directives/other.py

@@ -3,7 +3,7 @@
 import re
 from os.path import abspath, relpath
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -22,6 +22,8 @@
 from sphinx.util.nodes import explicit_title_re
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from docutils.nodes import Element, Node
 
     from sphinx.application import Sphinx
@@ -179,7 +181,7 @@ class Author(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         if not self.config.show_authors:
@@ -221,7 +223,7 @@ class TabularColumns(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         node = addnodes.tabular_col_spec()
@@ -239,7 +241,7 @@ class Centered(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         if not self.arguments:
@@ -262,7 +264,7 @@ class Acks(SphinxDirective):
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         node = addnodes.acks()
@@ -285,7 +287,7 @@ class HList(SphinxDirective):
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'columns': int,
     }
 
@@ -323,7 +325,7 @@ class Only(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         node = addnodes.only()
@@ -379,7 +381,7 @@ class Include(BaseInclude, SphinxDirective):
     "correctly", i.e. relative to source directory.
     """
 
-    def run(self) -> list[Node]:
+    def run(self) -> Sequence[Node]:
 
         # To properly emit "include-read" events from included RST text,
         # we must patch the ``StateMachine.insert_input()`` method.
@@ -413,7 +415,7 @@ def _insert_input(include_lines: list[str], source: str) -> None:
         # Only enable this patch if there are listeners for 'include-read'.
         if self.env.app.events.listeners.get('include-read'):
             # See https://github.com/python/mypy/issues/2427 for details on the mypy issue
-            self.state_machine.insert_input = _insert_input  # type: ignore[assignment]
+            self.state_machine.insert_input = _insert_input
 
         if self.arguments[0].startswith('<') and \
            self.arguments[0].endswith('>'):

sphinx/directives/patches.py

@@ -2,13 +2,13 @@
 
 import os
 from os import path
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, ClassVar, cast
 
 from docutils import nodes
 from docutils.nodes import Node, make_id
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives import images, tables
-from docutils.parsers.rst.directives.misc import Meta  # type: ignore[attr-defined]
+from docutils.parsers.rst.directives.misc import Meta
 from docutils.parsers.rst.roles import set_classes
 
 from sphinx.directives import optional_int
@@ -82,7 +82,7 @@ class Code(SphinxDirective):
     """
 
     optional_arguments = 1
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'class': directives.class_option,
         'force': directives.flag,
         'name': directives.unchanged,
@@ -127,7 +127,7 @@ class MathDirective(SphinxDirective):
     required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'label': directives.unchanged,
         'name': directives.unchanged,
         'class': directives.class_option,

sphinx/domains/c/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, ClassVar
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -56,7 +56,7 @@ class CObject(ObjectDescription[ASTDeclaration]):
     Description of a C language object.
     """
 
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'no-index-entry': directives.flag,
         'no-contents-entry': directives.flag,
         'no-typesetting': directives.flag,
@@ -297,7 +297,7 @@ class CNamespaceObject(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         rootSymbol = self.env.domaindata['c']['root_symbol']
@@ -327,7 +327,7 @@ class CNamespacePushObject(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         if self.arguments[0].strip() in ('NULL', '0', 'nullptr'):
@@ -358,7 +358,7 @@ class CNamespacePopObject(SphinxDirective):
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         stack = self.env.temp_data.get('c:namespace_stack', None)
@@ -517,7 +517,7 @@ def apply(self, **kwargs: Any) -> None:
 
 
 class CAliasObject(ObjectDescription):
-    option_spec: OptionSpec = {
+    option_spec: ClassVar[OptionSpec] = {
         'maxdepth': directives.nonnegative_int,
         'noroot': directives.flag,
     }

sphinx/domains/changeset.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, NamedTuple, cast
+from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple, cast
 
 from docutils import nodes
 
@@ -52,7 +52,7 @@ class VersionChange(SphinxDirective):
     required_arguments = 1
     optional_arguments = 1
     final_argument_whitespace = True
-    option_spec: OptionSpec = {}
+    option_spec: ClassVar[OptionSpec] = {}
 
     def run(self) -> list[Node]:
         node = addnodes.versionmodified()
@@ -123,7 +123,7 @@ def note_changeset(self, node: addnodes.versionmodified) -> None:
         version = node['version']
         module = self.env.ref_context.get('py:module')
         objname = self.env.temp_data.get('object')
-        changeset = ChangeSet(node['type'], self.env.docname, node.line,
+        changeset = ChangeSet(node['type'], self.env.docname, node.line,  # type: ignore[arg-type]
                               module, objname, node.astext())
         self.changesets.setdefault(version, []).append(changeset)