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

…utils`` type annotations (#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)