diff --git a/stubs/docutils/@tests/stubtest_allowlist.txt b/stubs/docutils/@tests/stubtest_allowlist.txt
index fe5bb9671661..5e747c6670f6 100644
--- a/stubs/docutils/@tests/stubtest_allowlist.txt
+++ b/stubs/docutils/@tests/stubtest_allowlist.txt
@@ -1,7 +1,9 @@
 docutils.nodes.Element.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__
 docutils.nodes.Element.tagname  # class variable is overridden in __init__ method
-docutils.nodes.NodeVisitor.depart_\w+  # Methods are discovered dynamically on commonly-used subclasses
+docutils.nodes.NodeVisitor.depart_\w+ # Methods are discovered dynamically on commonly-used subclasses
 docutils.nodes.NodeVisitor.visit_\w+  # Methods are discovered dynamically on commonly-used subclasses
+docutils.nodes.NodeVisitor.__init__   # Argument "document" should be positional-only, but subclasses are not
+
 # these methods take a rawsource parameter that has been deprecated and is completely ignored, so we omit it from the stub
 docutils.nodes.Text.__new__
 docutils.parsers.rst.directives.admonitions.BaseAdmonition.node_class  # must be overridden by base classes (pseudo-abstract)
@@ -11,8 +13,26 @@ docutils.statemachine.ViewList.__iter__ # doesn't exist at runtime, but the clas
 docutils.transforms.Transform.apply # method apply is not implemented
 docutils.transforms.Transform.__getattr__
 docutils.TransformSpec.unknown_reference_resolvers
+docutils.writers.latex2e.PreambleCmds... contents
 
 # Files that don't exist at runtime of stubtests, raises ImportError:
 docutils.parsers.commonmark_wrapper
 docutils.parsers.recommonmark_wrapper
 docutils.writers.odf_odt.pygmentsformatter # import `pygments` third-party library
+
+# `TYPE_CHECKING` variable is for internal use:
+docutils.TYPE_CHECKING
+docutils.core.TYPE_CHECKING
+docutils.examples.TYPE_CHECKING
+docutils.frontend.TYPE_CHECKING
+docutils.io.TYPE_CHECKING
+docutils.languages.TYPE_CHECKING
+docutils.nodes.TYPE_CHECKING
+docutils.parsers.TYPE_CHECKING
+docutils.parsers.rst.directives.TYPE_CHECKING
+docutils.parsers.rst.directives.misc.TYPE_CHECKING
+docutils.parsers.rst.languages.TYPE_CHECKING
+docutils.readers.TYPE_CHECKING
+docutils.utils.TYPE_CHECKING
+docutils.writers.TYPE_CHECKING
+docutils.writers._html_base.TYPE_CHECKING
diff --git a/stubs/docutils/METADATA.toml b/stubs/docutils/METADATA.toml
index 8976b59b905d..b556aa79aef4 100644
--- a/stubs/docutils/METADATA.toml
+++ b/stubs/docutils/METADATA.toml
@@ -1,2 +1,2 @@
-version = "0.21.*"
+version = "0.22.*"
 upstream_repository = "https://sourceforge.net/p/docutils/code"
diff --git a/stubs/docutils/docutils/__main__.pyi b/stubs/docutils/docutils/__main__.pyi
index 08e26dc7b297..819b94bd9593 100644
--- a/stubs/docutils/docutils/__main__.pyi
+++ b/stubs/docutils/docutils/__main__.pyi
@@ -1,7 +1,9 @@
-from typing import ClassVar
+from typing import ClassVar, Final
 
 import docutils
 
+__docformat__: Final = "reStructuredText"
+
 class CliSettingsSpec(docutils.SettingsSpec):
     config_section: ClassVar[str]
     config_section_dependencies: ClassVar[tuple[str, ...]]
diff --git a/stubs/docutils/docutils/core.pyi b/stubs/docutils/docutils/core.pyi
index 8d2818d0d8e2..bf436878fa38 100644
--- a/stubs/docutils/docutils/core.pyi
+++ b/stubs/docutils/docutils/core.pyi
@@ -3,7 +3,6 @@ from typing import Final
 from typing_extensions import deprecated
 
 from docutils import SettingsSpec
-from docutils.frontend import OptionParser
 from docutils.io import FileInput, Input, Output
 from docutils.parsers import Parser
 from docutils.readers import Reader
@@ -33,18 +32,10 @@ class Publisher:
         destination_class=...,
         settings: dict[str, Incomplete] | None = None,
     ) -> None: ...
-    def set_reader(self, reader_name: str, parser: Parser | None, parser_name: str | None) -> None: ...
+    def set_reader(self, reader: str, parser: Parser | None = None, parser_name: str | None = None) -> None: ...
     def set_writer(self, writer_name: str) -> None: ...
+    @deprecated("The `Publisher.set_components()` will be removed in Docutils 2.0.")
     def set_components(self, reader_name: str, parser_name: str, writer_name: str) -> None: ...
-    @deprecated("Publisher.setup_option_parser is deprecated, and will be removed in Docutils 0.21.")
-    def setup_option_parser(
-        self,
-        usage: str | None = None,
-        description: str | None = None,
-        settings_spec: SettingsSpec | None = None,
-        config_section: str | None = None,
-        **defaults,
-    ) -> OptionParser: ...
     def get_settings(
         self,
         usage: str | None = None,
@@ -64,7 +55,7 @@ class Publisher:
         **defaults,
     ) -> None: ...
     def set_io(self, source_path: StrPath | None = None, destination_path: StrPath | None = None) -> None: ...
-    def set_source(self, source=None, source_path: StrPath | None = None) -> None: ...
+    def set_source(self, source: str | None = None, source_path: StrPath | None = None) -> None: ...
     def set_destination(self, destination=None, destination_path: StrPath | None = None) -> None: ...
     def apply_transforms(self) -> None: ...
     def publish(
@@ -88,11 +79,11 @@ default_description: Final[str]
 
 def publish_cmdline(
     reader: Reader[Incomplete] | None = None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser: Parser | None = None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     writer: Writer[Incomplete] | None = None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
@@ -108,11 +99,11 @@ def publish_file(
     destination=None,
     destination_path: StrPath | None = None,
     reader=None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser=None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     writer=None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
@@ -124,11 +115,11 @@ def publish_string(
     source_path: StrPath | None = None,
     destination_path: StrPath | None = None,
     reader=None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser=None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     writer=None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
@@ -141,11 +132,11 @@ def publish_parts(
     source_class=...,
     destination_path: StrPath | None = None,
     reader=None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser=None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     writer=None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides: dict[str, Incomplete] | None = None,
@@ -157,9 +148,9 @@ def publish_doctree(
     source_path: StrPath | None = None,
     source_class=...,
     reader=None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser=None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
@@ -170,13 +161,14 @@ def publish_from_doctree(
     document,
     destination_path: StrPath | None = None,
     writer=None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
     config_section: str | None = None,
     enable_exit_status: bool = False,
 ): ...
+@deprecated("The `publish_cmdline_to_binary()` is deprecated  by `publish_cmdline()` and will be removed in Docutils 0.24.")
 def publish_cmdline_to_binary(
     reader=None,
     reader_name: str = "standalone",
diff --git a/stubs/docutils/docutils/examples.pyi b/stubs/docutils/docutils/examples.pyi
index 543969fa3079..42dd8c152903 100644
--- a/stubs/docutils/docutils/examples.pyi
+++ b/stubs/docutils/docutils/examples.pyi
@@ -1,27 +1,26 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, StrPath
 from typing import Literal, overload
 from typing_extensions import TypeAlias
 
 from docutils.core import Publisher
-from docutils.io import FileInput, StringInput
 from docutils.nodes import document
 from docutils.writers import _WriterParts
 
 _HTMLHeaderLevel: TypeAlias = Literal[1, 2, 3, 4, 5, 6]
 
 def html_parts(
-    input_string: str,
-    source_path=None,
-    destination_path=None,
+    input_string: str | bytes,
+    source_path: StrPath | None = None,
+    destination_path: StrPath | None = None,
     input_encoding: str = "unicode",
     doctitle: bool = True,
     initial_header_level: _HTMLHeaderLevel = 1,
 ) -> _WriterParts: ...
 @overload
 def html_body(
-    input_string: str,
-    source_path=None,
-    destination_path=None,
+    input_string: str | bytes,
+    source_path: StrPath | None = None,
+    destination_path: StrPath | None = None,
     input_encoding: str = "unicode",
     output_encoding: Literal["unicode"] = "unicode",
     doctitle: bool = True,
@@ -29,18 +28,17 @@ def html_body(
 ) -> str: ...
 @overload
 def html_body(
-    input_string: str,
-    source_path=None,
-    destination_path=None,
+    input_string: str | bytes,
+    source_path: StrPath | None = None,
+    destination_path: StrPath | None = None,
     input_encoding: str = "unicode",
     output_encoding: str = "unicode",
     doctitle: bool = True,
     initial_header_level: _HTMLHeaderLevel = 1,
 ) -> str | bytes: ...
 def internals(
-    input_string,
-    source_path: FileInput | StringInput | None = None,
-    destination_path: FileInput | StringInput | None = None,
+    source: str,
+    source_path: StrPath | None = None,
     input_encoding: str = "unicode",
     settings_overrides: dict[str, Incomplete] | None = None,
 ) -> tuple[document | None, Publisher]: ...
diff --git a/stubs/docutils/docutils/frontend.pyi b/stubs/docutils/docutils/frontend.pyi
index a8ed5f8b4506..276fae7a54cd 100644
--- a/stubs/docutils/docutils/frontend.pyi
+++ b/stubs/docutils/docutils/frontend.pyi
@@ -1,68 +1,168 @@
 import optparse
-from _typeshed import Incomplete
-from collections.abc import Iterable, Mapping
+from _typeshed import Incomplete, StrPath
+from collections.abc import Iterable, Mapping, Sequence
 from configparser import RawConfigParser
-from typing import Any, ClassVar, Final
+from typing import Any, ClassVar, Final, Literal, Protocol, overload, type_check_only
+from typing_extensions import deprecated
 
 from docutils import SettingsSpec
 from docutils.utils import DependencyList
 
 __docformat__: Final = "reStructuredText"
 
-def store_multiple(option, opt, value, parser, *args, **kwargs) -> None: ...
-def read_config_file(option, opt, value, parser) -> None: ...
-def validate_encoding(setting, value=None, option_parser=None, config_parser=None, config_section=None): ...
-def validate_encoding_error_handler(setting, value=None, option_parser=None, config_parser=None, config_section=None): ...
-def validate_encoding_and_error_handler(setting, value, option_parser, config_parser=None, config_section=None): ...
-def validate_boolean(setting, value=None, option_parser=None, config_parser=None, config_section=None) -> bool: ...
-def validate_ternary(setting, value=None, option_parser=None, config_parser=None, config_section=None): ...
-def validate_nonnegative_int(setting, value=None, option_parser=None, config_parser=None, config_section=None) -> int: ...
-def validate_threshold(setting, value=None, option_parser=None, config_parser=None, config_section=None) -> int: ...
+@type_check_only
+class _OptionValidator(Protocol):
+    def __call__(
+        self,
+        setting: str,
+        value: str | None,
+        option_parser: OptionParser,
+        /,
+        config_parser: ConfigParser | None = None,
+        config_section: str | None = None,
+    ) -> Any: ...
+
+@deprecated("Deprecated and will be removed with the switch to from optparse to argparse.")
+def store_multiple(option: optparse.Option, opt: str, value, parser: OptionParser, *args: str, **kwargs) -> None: ...
+@deprecated("Deprecated and will be removed with the switch to from optparse to argparse.")
+def read_config_file(option: optparse.Option, opt: str, value, parser: OptionParser) -> None: ...
+def validate_encoding(
+    setting: str,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> str: ...
+def validate_encoding_error_handler(
+    setting: str,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> str: ...
+def validate_encoding_and_error_handler(
+    setting: str,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> str: ...
+def validate_boolean(
+    setting: str | bool,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> bool: ...
+def validate_ternary(
+    setting: str | bool,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> str | bool | None: ...
+def validate_nonnegative_int(
+    setting: str | int,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> int: ...
+def validate_threshold(
+    setting: str | int,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> int: ...
 def validate_colon_separated_string_list(
-    setting, value=None, option_parser=None, config_parser=None, config_section=None
+    setting: str | list[str],
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
 ) -> list[str]: ...
 def validate_comma_separated_list(
-    setting, value=None, option_parser=None, config_parser=None, config_section=None
+    setting: str | list[str],
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
 ) -> list[str]: ...
-def validate_math_output(setting, value=None, option_parser=None, config_parser=None, config_section=None): ...
-def validate_url_trailing_slash(setting, value=None, option_parser=None, config_parser=None, config_section=None) -> str: ...
+def validate_math_output(
+    setting: str,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> tuple[()] | tuple[str, str]: ...
+def validate_url_trailing_slash(
+    setting: str,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> str: ...
 def validate_dependency_file(
-    setting, value=None, option_parser=None, config_parser=None, config_section=None
+    setting: str | None,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
 ) -> DependencyList: ...
-def validate_strip_class(setting, value=None, option_parser=None, config_parser=None, config_section=None): ...
+def validate_strip_class(
+    setting: str,
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> list[str]: ...
 def validate_smartquotes_locales(
-    setting, value=None, option_parser=None, config_parser=None, config_section=None
-) -> list[tuple[str, str]]: ...
-def make_paths_absolute(pathdict, keys, base_path=None) -> None: ...
-def make_one_path_absolute(base_path, path) -> str: ...
+    setting: str | list[str | tuple[str, str]],
+    value: str | None = None,
+    option_parser: OptionParser | None = None,
+    config_parser: ConfigParser | None = None,
+    config_section: str | None = None,
+) -> list[tuple[str, Sequence[str]]]: ...
+def make_paths_absolute(
+    pathdict: dict[str, list[StrPath] | StrPath], keys: tuple[str], base_path: StrPath | None = None
+) -> None: ...
+@deprecated("The `frontend.make_one_path_absolute` will be removed in Docutils 2.0 or later.")
+def make_one_path_absolute(base_path: StrPath, path: StrPath) -> str: ...
 def filter_settings_spec(settings_spec, *exclude, **replace) -> tuple[Any, ...]: ...
-
+@deprecated("The `frontend.Values` class will be removed in Docutils 2.0 or later.")
 class Values(optparse.Values):
-    record_dependencies: Incomplete
-    def __init__(self, *args, **kwargs) -> None: ...
-    def update(self, other_dict, option_parser) -> None: ...
+    record_dependencies: DependencyList
+    def __init__(self, defaults: dict[str, Any] | None = None) -> None: ...
+    def update(self, other_dict: Values | Mapping[str, Incomplete], option_parser: OptionParser) -> None: ...
     def copy(self) -> Values: ...
-    def setdefault(self, name, default): ...
+    def setdefault(self, name: str, default): ...
 
+@deprecated("The `frontend.Option` class will be removed in Docutils 2.0 or later.")
 class Option(optparse.Option):
-    ATTRS: Incomplete
-    def __init__(self, *args, **kwargs) -> None: ...
-    def process(self, opt, value, values, parser): ...
+    ATTRS: list[str]
+    validator: _OptionValidator
+    overrides: str | None
+    def __init__(self, *args: str | None, **kwargs) -> None: ...
 
+@deprecated(
+    "The `frontend.OptionParser` class will be replaced by a subclass of `argparse.ArgumentParser` in Docutils 2.0 or later."
+)
 class OptionParser(optparse.OptionParser, SettingsSpec):
     standard_config_files: ClassVar[list[str]]
-    threshold_choices: ClassVar[list[str]]
+    threshold_choices: ClassVar[tuple[str, ...]]
     thresholds: ClassVar[dict[str, int]]
     booleans: ClassVar[dict[str, bool]]
     default_error_encoding: ClassVar[str]
     default_error_encoding_error_handler: ClassVar[str]
     config_section: ClassVar[str]
     version_template: ClassVar[str]
-    lists: Incomplete
-    config_files: Incomplete
+    details: str
+    lists: dict[str, Literal[True]]
+    config_files: list[str]
     relative_path_settings: ClassVar[tuple[str, ...]]
-    version: Incomplete
-    components: Incomplete
+    version: str
+    components: tuple[SettingsSpec, ...]
     def __init__(
         self,
         components: Iterable[SettingsSpec | type[SettingsSpec]] = (),
@@ -71,27 +171,29 @@ class OptionParser(optparse.OptionParser, SettingsSpec):
         *args,
         **kwargs,
     ) -> None: ...
-    def populate_from_components(self, components) -> None: ...
+    def populate_from_components(self, components: Iterable[SettingsSpec]) -> None: ...
     @classmethod
-    def get_standard_config_files(cls): ...
-    def get_standard_config_settings(self): ...
-    def get_config_file_settings(self, config_file): ...
-    def check_values(self, values, args): ...
-    def check_args(self, args): ...
-    def set_defaults_from_dict(self, defaults) -> None: ...
-    def get_default_values(self): ...
-    def get_option_by_dest(self, dest): ...
+    def get_standard_config_files(cls) -> Sequence[StrPath]: ...
+    def get_standard_config_settings(self) -> Values: ...
+    def get_config_file_settings(self, config_file: str) -> dict[str, Incomplete]: ...
+    def check_values(self, values: Values, args: list[str]) -> Values: ...  # type: ignore[override]
+    def check_args(self, args: list[str]) -> tuple[str | None, str | None]: ...
+    def get_default_values(self) -> Values: ...
+    def get_option_by_dest(self, dest: str) -> Option: ...
 
 class ConfigParser(RawConfigParser):
-    old_settings: Incomplete
-    old_warning: str
-    not_utf8_error: str
-    def read(self, filenames, option_parser=None): ...
-    def handle_old_config(self, filename) -> None: ...
-    def validate_settings(self, filename, option_parser) -> None: ...
-    def optionxform(self, optionstr): ...
-    def get_section(self, section): ...
+    old_settings: ClassVar[dict[str, tuple[str, str]]]
+    old_warning: ClassVar[str]
+    not_utf8_error: ClassVar[str]
+    @overload  # type: ignore[override]
+    def read(self, filenames: str | Sequence[str], option_parser: None = None) -> list[str]: ...
+    @overload
+    @deprecated("The `option_parser` parameter is deprecated and will be removed in Docutils 0.24.")
+    def read(self, filenames: str | Sequence[str], option_parser: OptionParser = ...) -> list[str]: ...
+    def handle_old_config(self, filename: str) -> None: ...
+    def validate_settings(self, filename: str, option_parser: OptionParser) -> None: ...
+    def optionxform(self, optionstr: str) -> str: ...
 
 class ConfigDeprecationWarning(FutureWarning): ...
 
-def get_default_settings(*components) -> Values: ...
+def get_default_settings(*components: SettingsSpec) -> Values: ...
diff --git a/stubs/docutils/docutils/io.pyi b/stubs/docutils/docutils/io.pyi
index 5b04fdb71257..34fad7790bb4 100644
--- a/stubs/docutils/docutils/io.pyi
+++ b/stubs/docutils/docutils/io.pyi
@@ -8,7 +8,8 @@ from _typeshed import (
     Unused,
 )
 from re import Pattern
-from typing import IO, Any, ClassVar, Final, Generic, Literal, TypeVar
+from typing import IO, Any, ClassVar, Final, Generic, Literal, TextIO, TypeVar
+from typing_extensions import deprecated
 
 from docutils import TransformSpec, nodes
 
@@ -17,7 +18,7 @@ __docformat__: Final = "reStructuredText"
 class InputError(OSError): ...
 class OutputError(OSError): ...
 
-def check_encoding(stream: Any, encoding: str) -> bool | None: ...
+def check_encoding(stream: TextIO, encoding: str) -> bool | None: ...
 def error_string(err: BaseException) -> str: ...
 
 _S = TypeVar("_S")
@@ -31,12 +32,17 @@ class Input(TransformSpec, Generic[_S]):
     source_path: str | None
     successful_encoding: str | None = None
     def __init__(
-        self, source: _S | None = None, source_path: str | None = None, encoding: str | None = None, error_handler: str = "strict"
+        self,
+        source: _S | None = None,
+        source_path: str | None = None,
+        encoding: str | None = "utf-8",
+        error_handler: str = "strict",
     ) -> None: ...
     def read(self) -> str: ...
     def decode(self, data: str | bytes | bytearray) -> str: ...
     coding_slug: ClassVar[Pattern[bytes]]
     byte_order_marks: ClassVar[tuple[tuple[bytes, str], ...]]
+    @deprecated("Deprecated and will be removed in Docutils 1.0.")
     def determine_encoding_from_data(self, data: str | bytes | bytearray) -> str | None: ...
     def isatty(self) -> bool: ...
 
@@ -70,14 +76,12 @@ class ErrorOutput:
     def isatty(self) -> bool: ...
 
 class FileInput(Input[IO[str]]):
-    autoclose: Incomplete
-    source: Incomplete
-    source_path: Incomplete
+    autoclose: bool
     def __init__(
         self,
         source=None,
         source_path=None,
-        encoding: str | None = None,
+        encoding: str | None = "utf-8",
         error_handler: str = "strict",
         autoclose: bool = True,
         mode: OpenTextModeReading | OpenBinaryModeReading = "r",
@@ -107,6 +111,7 @@ class FileOutput(Output):
     def write(self, data): ...
     def close(self) -> None: ...
 
+@deprecated("The `BinaryFileOutput` is deprecated by `FileOutput` and will be removed in Docutils 0.24.")
 class BinaryFileOutput(FileOutput): ...
 
 class StringInput(Input[str]):
diff --git a/stubs/docutils/docutils/languages/__init__.pyi b/stubs/docutils/docutils/languages/__init__.pyi
index d04730262182..415e42286a17 100644
--- a/stubs/docutils/docutils/languages/__init__.pyi
+++ b/stubs/docutils/docutils/languages/__init__.pyi
@@ -1,4 +1,5 @@
 from typing import ClassVar, Final, Protocol, type_check_only
+from typing_extensions import Self
 
 from docutils.utils import Reporter
 
@@ -19,5 +20,6 @@ class LanguageImporter:
     def import_from_packages(self, name: str, reporter: Reporter | None = None) -> _LanguageModule: ...
     def check_content(self, module: _LanguageModule) -> None: ...
     def __call__(self, language_code: str, reporter: Reporter | None = None) -> _LanguageModule: ...
+    def __class_getitem__(cls, name) -> type[Self]: ...
 
 get_language: LanguageImporter
diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi
index fb9fcf0eb9b6..e6c937185c4c 100644
--- a/stubs/docutils/docutils/nodes.pyi
+++ b/stubs/docutils/docutils/nodes.pyi
@@ -1,16 +1,21 @@
 import sys
 import xml.dom.minidom
+from _typeshed import Incomplete
 from abc import abstractmethod
 from collections import Counter
 from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence
 from typing import Any, ClassVar, Final, Literal, Protocol, SupportsIndex, TypeVar, overload
-from typing_extensions import Self, TypeAlias
+from typing_extensions import Self, TypeAlias, deprecated
 
 from docutils.frontend import Values
 from docutils.transforms import Transform, Transformer
 from docutils.utils import Reporter
 
 _N = TypeVar("_N", bound=Node)
+_ContentModelCategory: TypeAlias = type[Element] | tuple[type[Element], ...]
+_ContentModelQuantifier: TypeAlias = Literal[".", "?", "+", "*"]
+_ContentModelItem: TypeAlias = tuple[_ContentModelCategory, _ContentModelQuantifier]
+_ContentModelTuple: TypeAlias = tuple[_ContentModelItem, ...]
 
 class _DomModule(Protocol):
     Document: type[xml.dom.minidom.Document]
@@ -33,7 +38,9 @@ class Node:
     @document.setter
     def document(self, value: document) -> None: ...
     def __bool__(self) -> Literal[True]: ...
-    def asdom(self, dom: _DomModule | None = None) -> xml.dom.minidom.Element: ...
+    def asdom(
+        self, dom: _DomModule | None = None
+    ) -> xml.dom.minidom.Document | xml.dom.minidom.Element | xml.dom.minidom.Text: ...
     # While docutils documents the Node class to be abstract it does not
     # actually use the ABCMeta metaclass. We still set @abstractmethod here
     # (although it's not used in the docutils implementation) because it
@@ -52,7 +59,7 @@ class Node:
     @overload
     def findall(
         self, condition: type[_N], include_self: bool = True, descend: bool = True, siblings: bool = False, ascend: bool = False
-    ) -> Generator[_N, None, None]: ...
+    ) -> Generator[_N]: ...
     @overload
     def findall(
         self,
@@ -61,12 +68,14 @@ class Node:
         descend: bool = True,
         siblings: bool = False,
         ascend: bool = False,
-    ) -> Generator[Node, None, None]: ...
+    ) -> Generator[Node]: ...
     @overload
+    @deprecated("The `nodes.Node.traverse()` is deprecated. Use `Node.findall()` instead.")
     def traverse(
         self, condition: type[_N], include_self: bool = True, descend: bool = True, siblings: bool = False, ascend: bool = False
     ) -> list[_N]: ...
     @overload
+    @deprecated("The `nodes.Node.traverse()` is deprecated. Use `Node.findall()` instead.")
     def traverse(
         self,
         condition: Callable[[Node], bool] | None = None,
@@ -88,6 +97,8 @@ class Node:
         siblings: bool = False,
         ascend: bool = False,
     ) -> Node: ...
+    def validate(self, recursive: bool = True) -> None: ...
+    def validate_position(self) -> None: ...
 
 # Left out
 # - def ensure_str (deprecated)
@@ -113,9 +124,12 @@ _T = TypeVar("_T")
 
 class Element(Node):
     local_attributes: ClassVar[Sequence[str]]
+    valid_attributes: ClassVar[Sequence[str]]
+    common_attributes: ClassVar[Sequence[str]]
     basic_attributes: ClassVar[Sequence[str]]
     list_attributes: ClassVar[Sequence[str]]
     known_attributes: ClassVar[Sequence[str]]
+    content_model: ClassVar[_ContentModelTuple]
     tagname: str
     child_text_separator: ClassVar[str]
     attributes: dict[str, Any]
@@ -166,6 +180,7 @@ class Element(Node):
     def remove(self, item: Node) -> None: ...
     def index(self, item: Node, start: int = 0, stop: int = sys.maxsize) -> int: ...
     def previous_sibling(self) -> Node | None: ...
+    def section_hierarchy(self) -> list[section]: ...
     def is_not_default(self, key: str) -> bool: ...
     def update_basic_atts(self, dict_: Mapping[str, Any] | Node) -> None: ...
     def append_attr_list(self, attr: str, values: Iterable[Any]) -> None: ...
@@ -204,12 +219,15 @@ class Element(Node):
     def pformat(self, indent: str = "    ", level: int = 0) -> str: ...
     def copy(self) -> Self: ...
     def deepcopy(self) -> Self: ...
-    def set_class(self, name: str) -> None: ...
     def note_referenced_by(self, name: str | None = None, id: str | None = None) -> None: ...
     @classmethod
     def is_not_list_attribute(cls, attr: str) -> bool: ...
     @classmethod
     def is_not_known_attribute(cls, attr: str) -> bool: ...
+    def validate_attributes(self) -> None: ...
+    def validate_content(
+        self, model: _ContentModelTuple | None = None, elements: Sequence[Incomplete] | None = None
+    ) -> list[Incomplete]: ...
 
     # '__iter__' is added as workaround, since mypy doesn't support classes that are iterable via '__getitem__'
     # see https://github.com/python/typeshed/pull/10099#issuecomment-1528789395
@@ -219,6 +237,7 @@ class TextElement(Element):
     def __init__(self, rawsource: str = "", text: str = "", *children: Node, **attributes) -> None: ...
 
 class FixedTextElement(TextElement): ...
+class PureTextElement(TextElement): ...
 
 # Mixins
 
@@ -226,6 +245,8 @@ class Resolvable:
     resolved: int
 
 class BackLinkable:
+    list_attributes: ClassVar[Sequence[str]]
+    valid_attributes: ClassVar[Sequence[str]]
     def add_backref(self, refid: str) -> None: ...
 
 # Element Categories
@@ -234,12 +255,19 @@ class Root: ...
 class Titular: ...
 class PreBibliographic: ...
 class Bibliographic: ...
-class Decorative(PreBibliographic): ...
+
+class Decorative(PreBibliographic):
+    content_model: ClassVar[_ContentModelTuple]
+
 class Structural: ...
+class SubStructural: ...
 class Body: ...
 class General(Body): ...
 class Sequential(Body): ...
-class Admonition(Body): ...
+
+class Admonition(Body):
+    content_model: ClassVar[_ContentModelTuple]
+
 class Special(Body): ...
 class Invisible(PreBibliographic): ...
 class Part: ...
@@ -289,7 +317,7 @@ class document(Root, Structural, Element):
     def __init__(self, settings: Values, reporter: Reporter, *args: Node, **kwargs: Any) -> None: ...
     def asdom(self, dom: Any | None = None) -> Any: ...
     def set_id(self, node: Element, msgnode: Element | None = None, suggested_prefix: str = "") -> str: ...
-    def set_name_id_map(self, node: Element, id: str, msgnode: Element | None = None, explicit: bool | None = None) -> None: ...
+    def set_name_id_map(self, node: Element, id: str, msgnode: Element | None = None, explicit: bool = False) -> None: ...
     def set_duplicate_name_id(self, node: Element, id: str, name: str, msgnode: Element, explicit: bool) -> None: ...
     def has_name(self, name: str) -> bool: ...
     def note_implicit_target(self, target: Element, msgnode: Element | None = None) -> None: ...
@@ -411,7 +439,10 @@ class caption(Part, TextElement): ...
 class legend(Part, Element): ...
 class table(General, Element): ...
 class tgroup(Part, Element): ...
-class colspec(Part, Element): ...
+
+class colspec(Part, Element):
+    def propwidth(self) -> float: ...
+
 class thead(Part, Element): ...
 class tbody(Part, Element): ...
 class row(Part, Element): ...
@@ -682,6 +713,9 @@ class TreeCopyVisitor(GenericNodeVisitor):
     parent: list[Node]
     def get_tree_copy(self) -> Node: ...
 
+class ValidationError(ValueError):
+    def __init__(self, msg: str, problematic_element: Element | None = None) -> None: ...
+
 class TreePruningException(Exception): ...
 class SkipChildren(TreePruningException): ...
 class SkipSiblings(TreePruningException): ...
@@ -695,4 +729,17 @@ def dupname(node: Node, name: str) -> None: ...
 def fully_normalize_name(name: str) -> str: ...
 def whitespace_normalize_name(name: str) -> str: ...
 def serial_escape(value: str) -> str: ...
+def split_name_list(s: str) -> list[str]: ...
 def pseudo_quoteattr(value: str) -> str: ...
+def parse_measure(measure: str, unit_pattern: str = "[a-zA-Zµ]*|%?") -> tuple[float, str]: ...
+def create_keyword_validator(*keywords: str) -> Callable[[str], str]: ...
+def validate_identifier(value: str) -> str: ...
+def validate_identifier_list(value: str | list[str]) -> list[str]: ...
+def validate_measure(measure: str) -> str: ...
+def validate_colwidth(measure: str | float) -> float: ...
+def validate_NMTOKEN(value: str) -> str: ...
+def validate_NMTOKENS(value: str | list[str]) -> list[str]: ...
+def validate_refname_list(value: str | list[str]) -> list[str]: ...
+def validate_yesorno(value: str | int | bool) -> bool: ...
+
+ATTRIBUTE_VALIDATORS: dict[str, Callable[[str], Any]]
diff --git a/stubs/docutils/docutils/parsers/__init__.pyi b/stubs/docutils/docutils/parsers/__init__.pyi
index 1c301b050641..d15966c81088 100644
--- a/stubs/docutils/docutils/parsers/__init__.pyi
+++ b/stubs/docutils/docutils/parsers/__init__.pyi
@@ -14,6 +14,6 @@ class Parser(Component):
     def setup_parse(self, inputstring: str, document: _Document) -> None: ...
     def finish_parse(self) -> None: ...
 
-_parser_aliases: dict[str, str]
+PARSER_ALIASES: Final[dict[str, str]]
 
 def get_parser_class(parser_name: str) -> type[Parser]: ...
diff --git a/stubs/docutils/docutils/parsers/docutils_xml.pyi b/stubs/docutils/docutils/parsers/docutils_xml.pyi
new file mode 100644
index 000000000000..d8351b0c7ea8
--- /dev/null
+++ b/stubs/docutils/docutils/parsers/docutils_xml.pyi
@@ -0,0 +1,16 @@
+import xml.etree.ElementTree as ET
+from typing import ClassVar, Final
+
+from docutils import nodes, parsers
+
+__docformat__: Final = "reStructuredText"
+
+class Parser(parsers.Parser):
+    config_section_dependencies: ClassVar[tuple[str, ...]]
+    settings_default_overrides: ClassVar[dict[str, bool]]
+
+class Unknown(nodes.Special, nodes.Inline, nodes.Element): ...
+
+def parse_element(inputstring: str, document: nodes.document | None = None) -> nodes.Element: ...
+def element2node(element: ET.Element | None, document: nodes.document | None = None, unindent: bool = True) -> nodes.Element: ...
+def append_text(node: nodes.Element, text: str | None, unindent: bool | None) -> None: ...
diff --git a/stubs/docutils/docutils/parsers/null.pyi b/stubs/docutils/docutils/parsers/null.pyi
index bd88e09cdfab..ff81ca28c7fd 100644
--- a/stubs/docutils/docutils/parsers/null.pyi
+++ b/stubs/docutils/docutils/parsers/null.pyi
@@ -1,7 +1,9 @@
-from typing import ClassVar
+from typing import ClassVar, Final
 
 from docutils import parsers
 
+__docformat__: Final = "reStructuredText"
+
 class Parser(parsers.Parser):
     supported: ClassVar[tuple[str, ...]]
     config_section_dependencies: ClassVar[tuple[str, ...]]
diff --git a/stubs/docutils/docutils/parsers/recommonmark_wrapper.pyi b/stubs/docutils/docutils/parsers/recommonmark_wrapper.pyi
index 93a20f579660..c085b367af92 100644
--- a/stubs/docutils/docutils/parsers/recommonmark_wrapper.pyi
+++ b/stubs/docutils/docutils/parsers/recommonmark_wrapper.pyi
@@ -1,15 +1,18 @@
 from types import ModuleType
 from typing import ClassVar
+from typing_extensions import deprecated
 
 from docutils import nodes
 from docutils.transforms import Transform
 
+@deprecated("The `recommonmark` package is unmaintained and deprecated; will be removed in Docutils 1.0.")
 class pending_xref(nodes.Inline, nodes.Element): ...
 
 sphinx: ModuleType
 
+@deprecated("The `recommonmark` package is unmaintained and deprecated; will be removed in Docutils 1.0.")
 def is_literal(node: nodes.Node) -> bool: ...
-
+@deprecated("The `recommonmark` package is unmaintained and deprecated; will be removed in Docutils 1.0.")
 class _CommonMarkParser:
     default_config: ClassVar[dict[str, None]]
     def __init__(self) -> None: ...
@@ -40,6 +43,7 @@ class _CommonMarkParser:
     def add_section(self, section, level): ...
     def is_section_level(self, level, section): ...
 
+@deprecated("The `recommonmark` package is unmaintained and deprecated; will be removed in Docutils 1.0.")
 class Parser(_CommonMarkParser):
     supported: ClassVar[tuple[str, ...]]
     config_section: ClassVar[str]
diff --git a/stubs/docutils/docutils/parsers/rst/directives/__init__.pyi b/stubs/docutils/docutils/parsers/rst/directives/__init__.pyi
index 70c4c07af847..501bb87ddaf9 100644
--- a/stubs/docutils/docutils/parsers/rst/directives/__init__.pyi
+++ b/stubs/docutils/docutils/parsers/rst/directives/__init__.pyi
@@ -21,6 +21,7 @@ def uri(argument: str) -> str: ...
 def nonnegative_int(argument: str) -> int: ...
 def percentage(argument: str) -> int: ...
 
+CSS3_LENGTH_UNITS: Final[tuple[str, ...]]
 length_units: Final[list[str]]
 
 def get_measure(argument: str, units: Iterable[str]) -> str: ...
diff --git a/stubs/docutils/docutils/parsers/rst/directives/misc.pyi b/stubs/docutils/docutils/parsers/rst/directives/misc.pyi
index 963bc77ef1d5..46b89b555d45 100644
--- a/stubs/docutils/docutils/parsers/rst/directives/misc.pyi
+++ b/stubs/docutils/docutils/parsers/rst/directives/misc.pyi
@@ -3,15 +3,21 @@ from pathlib import Path
 from re import Match, Pattern
 from typing import ClassVar, Final
 
+from docutils import nodes
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst.states import SpecializedBody
 
 __docformat__: Final = "reStructuredText"
 
-def adapt_path(path: str, source: StrPath = "", root_prefix: StrPath = "/") -> str: ...
+def adapt_path(path: str, source: StrPath = "", root_prefix: StrPath = "") -> str: ...
 
 class Include(Directive):
     standard_include_path: Path
+    def read_file(self, path: StrPath) -> str: ...
+    def as_literal_block(self, text: str) -> list[nodes.literal_block]: ...
+    def as_code_block(self, text: str) -> list[nodes.literal_block]: ...
+    def custom_parse(self, text: str) -> list[nodes.Node]: ...
+    def insert_into_input_lines(self, text: str) -> None: ...
 
 class Raw(Directive): ...
 class Replace(Directive): ...
diff --git a/stubs/docutils/docutils/parsers/rst/directives/tables.pyi b/stubs/docutils/docutils/parsers/rst/directives/tables.pyi
index ebde406d577e..971aee28dfcd 100644
--- a/stubs/docutils/docutils/parsers/rst/directives/tables.pyi
+++ b/stubs/docutils/docutils/parsers/rst/directives/tables.pyi
@@ -2,6 +2,7 @@ import csv
 from _typeshed import Incomplete
 from collections.abc import Callable
 from typing import ClassVar, Final
+from typing_extensions import deprecated
 
 from docutils.parsers.rst import Directive
 
@@ -34,6 +35,7 @@ class CSVTable(Table):
         escapechar: Incomplete
         def __init__(self, options) -> None: ...
 
+    @deprecated("Deprecated and will be removed in Docutils 1.0.")
     class HeaderDialect(csv.Dialect):
         delimiter: str
         quotechar: str
@@ -46,14 +48,11 @@ class CSVTable(Table):
         def __init__(self) -> None: ...
 
     @staticmethod
+    @deprecated("Deprecated and not required with Python 3; will be removed in Docutils 0.22.")
     def check_requirements() -> None: ...
     def process_header_option(self): ...
     def run(self): ...
     def get_csv_data(self): ...
-    @staticmethod
-    def decode_from_csv(s): ...
-    @staticmethod
-    def encode_for_csv(s): ...
     def parse_csv_data_into_rows(self, csv_data, dialect, source): ...
 
 class ListTable(Table):
diff --git a/stubs/docutils/docutils/parsers/rst/roles.pyi b/stubs/docutils/docutils/parsers/rst/roles.pyi
index eb1b39446de0..eb238c6f4905 100644
--- a/stubs/docutils/docutils/parsers/rst/roles.pyi
+++ b/stubs/docutils/docutils/parsers/rst/roles.pyi
@@ -1,6 +1,6 @@
 from collections.abc import Callable, Mapping, Sequence
 from typing import Any, Final
-from typing_extensions import TypeAlias
+from typing_extensions import TypeAlias, deprecated
 
 import docutils.parsers.rst.states
 from docutils import nodes
@@ -128,5 +128,8 @@ def unimplemented_role(
     options: Mapping[str, Any] | None = None,
     content: Sequence[str] | None = None,
 ) -> tuple[list[Node], list[system_message]]: ...
+@deprecated("Deprecated and will be removed in Docutils 2.0, Use `roles.normalize_options()` instead.")
 def set_classes(options: dict[str, str]) -> None: ...
+@deprecated("Deprecated and will be removed in Docutils 2.0, Use `roles.normalize_options()` instead.")
 def normalized_role_options(options: Mapping[str, Any] | None) -> dict[str, Any]: ...
+def normalize_options(options: Mapping[str, Any] | None) -> dict[str, Any]: ...
diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi
index 169b1699c7b4..1384623c7a84 100644
--- a/stubs/docutils/docutils/parsers/rst/states.pyi
+++ b/stubs/docutils/docutils/parsers/rst/states.pyi
@@ -1,7 +1,7 @@
 from _typeshed import Incomplete
 from collections.abc import Callable, Iterable, Sequence
 from re import Match, Pattern
-from types import ModuleType
+from types import ModuleType, SimpleNamespace as Struct
 from typing import Any, ClassVar, Final, NoReturn
 from typing_extensions import TypeAlias
 
@@ -19,9 +19,6 @@ class InterpretedRoleNotImplementedError(DataError): ...
 class ParserError(ApplicationError): ...
 class MarkupMismatch(Exception): ...
 
-class Struct:
-    def __init__(self, **keywordargs) -> None: ...
-
 class RSTStateMachine(StateMachineWS[list[str]]):
     language: _RstLanguageModule
     match_titles: bool
@@ -92,7 +89,7 @@ class RSTState(StateWS[list[str]]):
     def inline_text(self, text: str, lineno: int) -> tuple[list[Node], list[system_message]]: ...
     def unindent_warning(self, node_name: str): ...
 
-def build_regexp(definition, compile: bool = True): ...
+def build_regexp(definition, compile_patterns: bool | None = True): ...
 
 _BasicDefinition: TypeAlias = tuple[str, str, str, list[Pattern[str]]]
 _DefinitionParts: TypeAlias = tuple[str, str, str, list[Pattern[str] | _BasicDefinition]]
diff --git a/stubs/docutils/docutils/readers/doctree.pyi b/stubs/docutils/docutils/readers/doctree.pyi
index a3075e56927d..27be5d0e1f0e 100644
--- a/stubs/docutils/docutils/readers/doctree.pyi
+++ b/stubs/docutils/docutils/readers/doctree.pyi
@@ -1,8 +1,10 @@
-from typing import ClassVar, TypeVar
+from typing import ClassVar, Final, TypeVar
 
 from docutils import readers
 
 _S = TypeVar("_S", bound=str | bytes)
 
+__docformat__: Final = "reStructuredText"
+
 class Reader(readers.ReReader[_S]):
     config_section_dependencies: ClassVar[tuple[str, ...]]
diff --git a/stubs/docutils/docutils/transforms/references.pyi b/stubs/docutils/docutils/transforms/references.pyi
index ccc85bddb037..a5a0068180f6 100644
--- a/stubs/docutils/docutils/transforms/references.pyi
+++ b/stubs/docutils/docutils/transforms/references.pyi
@@ -62,6 +62,10 @@ class TargetNotes(Transform):
     def apply(self) -> None: ...
     def make_target_footnote(self, refuri: str, refs: list[Incomplete], notes: dict[Incomplete, Incomplete]): ...
 
+class CitationReferences(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
 class DanglingReferences(Transform):
     default_priority: ClassVar[int]
     def apply(self) -> None: ...
diff --git a/stubs/docutils/docutils/transforms/universal.pyi b/stubs/docutils/docutils/transforms/universal.pyi
index 50dca81cc671..78879e80f994 100644
--- a/stubs/docutils/docutils/transforms/universal.pyi
+++ b/stubs/docutils/docutils/transforms/universal.pyi
@@ -50,3 +50,7 @@ class SmartQuotes(Transform):
     def __init__(self, document: nodes.document, startnode: nodes.Node | None) -> None: ...
     def get_tokens(self, txtnodes: Iterable[nodes.Node]) -> Generator[tuple[Literal["literal", "plain"], str]]: ...
     def apply(self) -> None: ...
+
+class Validate(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
diff --git a/stubs/docutils/docutils/transforms/writer_aux.pyi b/stubs/docutils/docutils/transforms/writer_aux.pyi
index dc37428a259d..38523f07319e 100644
--- a/stubs/docutils/docutils/transforms/writer_aux.pyi
+++ b/stubs/docutils/docutils/transforms/writer_aux.pyi
@@ -1,17 +1,9 @@
 from typing import ClassVar, Final
-from typing_extensions import deprecated
 
-from docutils import nodes
 from docutils.transforms import Transform
 
 __docformat__: Final = "reStructuredText"
 
-@deprecated("docutils.transforms.writer_aux.Compound is deprecated and will be removed in Docutils 0.21 or later.")
-class Compound(Transform):
-    default_priority: ClassVar[int]
-    def __init__(self, document: nodes.document, startnode: nodes.Node | None = None) -> None: ...
-    def apply(self) -> None: ...
-
 class Admonitions(Transform):
     default_priority: ClassVar[int]
     def apply(self) -> None: ...
diff --git a/stubs/docutils/docutils/utils/__init__.pyi b/stubs/docutils/docutils/utils/__init__.pyi
index 9299145afd02..30b4725712a4 100644
--- a/stubs/docutils/docutils/utils/__init__.pyi
+++ b/stubs/docutils/docutils/utils/__init__.pyi
@@ -1,9 +1,9 @@
 import optparse
-from _typeshed import StrPath, SupportsWrite, Unused
-from collections.abc import Callable, Iterable, Mapping
+from _typeshed import StrPath, SupportsWrite
+from collections.abc import Callable, Iterable, Mapping, Sequence
 from re import Pattern
 from typing import Any, Final, Literal, TypeVar
-from typing_extensions import TypeAlias
+from typing_extensions import TypeAlias, deprecated
 
 from docutils import ApplicationError, DataError, nodes
 from docutils.frontend import Values
@@ -27,13 +27,14 @@ class DependencyList:
 class SystemMessagePropagation(ApplicationError): ...
 
 class Reporter:
-    levels: list[str]
+    get_source_and_line: Callable[[int | None], tuple[StrPath | None, int | None]]
+    levels: Final[Sequence[str]]
 
-    DEBUG_LEVEL: Literal[0]
-    INFO_LEVEL: Literal[1]
-    WARNING_LEVEL: Literal[2]
-    ERROR_LEVEL: Literal[3]
-    SEVERE_LEVEL: Literal[4]
+    DEBUG_LEVEL: Final = 0
+    INFO_LEVEL: Final = 1
+    WARNING_LEVEL: Final = 2
+    ERROR_LEVEL: Final = 3
+    SEVERE_LEVEL: Final = 4
 
     stream: ErrorOutput
     encoding: str
@@ -55,14 +56,6 @@ class Reporter:
     debug_flag: bool
     report_level: _SystemMessageLevel
     halt_level: int
-    def set_conditions(
-        self,
-        category: Unused,
-        report_level: int,
-        halt_level: int,
-        stream: SupportsWrite[str] | SupportsWrite[bytes] | None = None,
-        debug: bool = False,
-    ) -> None: ...
     def attach_observer(self, observer: _Observer) -> None: ...
     def detach_observer(self, observer: _Observer) -> None: ...
     def notify_observers(self, message: nodes.system_message) -> None: ...
@@ -113,11 +106,13 @@ def assemble_option_dict(
 
 class NameValueError(DataError): ...
 
+@deprecated("Deprecated and will be removed in Docutils 1.0.")
 def decode_path(path: str) -> str: ...
 def extract_name_value(line: str) -> list[tuple[str, str]]: ...
 def clean_rcs_keywords(paragraph: nodes.paragraph, keyword_substitutions: Iterable[tuple[Pattern[str], str]]) -> None: ...
 def relative_path(source: StrPath | None, target: StrPath) -> str: ...
-def get_stylesheet_reference(settings: Values, relative_to: str | None = None) -> str: ...
+@deprecated("Deprecated and will be removed in Docutils 1.0. Use `get_stylesheet_list()` instead.")
+def get_stylesheet_reference(settings: Values, relative_to: StrPath | None = None) -> str: ...
 def get_stylesheet_list(settings: Values) -> list[str]: ...
 def find_file_in_dirs(path: StrPath, dirs: Iterable[StrPath]) -> str: ...
 def get_trim_footnote_ref_space(settings: Values) -> bool: ...
@@ -134,7 +129,3 @@ def column_width(text: str) -> int: ...
 def uniq(L: list[_T]) -> list[_T]: ...
 def normalize_language_tag(tag: str) -> list[str]: ...
 def xml_declaration(encoding: str | None = None) -> str: ...
-
-release_level_abbreviations: dict[str, str]
-
-def version_identifier(version_info: tuple[int, int, int, str, int, bool] | None = None) -> str: ...
diff --git a/stubs/docutils/docutils/utils/_roman_numerals.pyi b/stubs/docutils/docutils/utils/_roman_numerals.pyi
new file mode 100644
index 000000000000..1dd10efcc8f9
--- /dev/null
+++ b/stubs/docutils/docutils/utils/_roman_numerals.pyi
@@ -0,0 +1,29 @@
+from typing import Final, final
+from typing_extensions import Self
+
+__all__ = ("MAX", "MIN", "InvalidRomanNumeralError", "OutOfRangeError", "RomanNumeral")
+
+MIN: Final = 1
+MAX: Final = 4_999
+
+@final
+class OutOfRangeError(TypeError): ...
+
+@final
+class InvalidRomanNumeralError(ValueError):
+    def __init__(self, value: str, *args: object) -> None: ...
+
+@final
+class RomanNumeral:
+    def __init__(self, value: int, /) -> None: ...
+    def __int__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __lt__(self, other: object) -> bool: ...
+    def __hash__(self) -> int: ...
+    def __setattr__(self, key: str, value: object) -> None: ...
+    def to_uppercase(self) -> str: ...
+    def to_lowercase(self) -> str: ...
+    @classmethod
+    def from_string(cls, string: str, /) -> Self: ...
+
+_ROMAN_NUMERAL_PREFIXES: Final[list[tuple[int, str, str]]]
diff --git a/stubs/docutils/docutils/utils/code_analyzer.pyi b/stubs/docutils/docutils/utils/code_analyzer.pyi
index 73313a959ea2..adbf7b956363 100644
--- a/stubs/docutils/docutils/utils/code_analyzer.pyi
+++ b/stubs/docutils/docutils/utils/code_analyzer.pyi
@@ -1,11 +1,12 @@
 from collections.abc import Generator, Iterable
-from typing import Literal
+from typing import Final, Literal
 from typing_extensions import TypeAlias
 
 from docutils import ApplicationError
 
 _TokenNames: TypeAlias = Literal["long", "short", "none"]
 
+__docformat__: Final = "reStructuredText"
 with_pygments: bool
 unstyled_tokens: list[str]
 
diff --git a/stubs/docutils/docutils/utils/error_reporting.pyi b/stubs/docutils/docutils/utils/error_reporting.pyi
deleted file mode 100644
index eed08a3c7b88..000000000000
--- a/stubs/docutils/docutils/utils/error_reporting.pyi
+++ /dev/null
@@ -1,41 +0,0 @@
-from io import TextIOWrapper
-from typing import TextIO
-from typing_extensions import TypeAlias, deprecated
-
-unicode = str
-
-_DataType: TypeAlias = str | Exception
-
-@deprecated("`docutils.utils.error_reporting` module is deprecated and will be removed in Docutils 0.21 or later.")
-class SafeString:
-    data: object
-    encoding: str
-    encoding_errors: str
-    decoding_errors: str
-    def __init__(
-        self,
-        data: object,
-        encoding: str | None = None,
-        encoding_errors: str = "backslashreplace",
-        decoding_errors: str = "replace",
-    ) -> None: ...
-    def __unicode__(self) -> str: ...
-
-@deprecated("`docutils.utils.error_reporting` module is deprecated and will be removed in Docutils 0.21 or later.")
-class ErrorString(SafeString): ...
-
-@deprecated("`docutils.utils.error_reporting` module is deprecated and will be removed in Docutils 0.21 or later.")
-class ErrorOutput:
-    stream: TextIO | TextIOWrapper
-    encoding: str
-    encoding_errors: str
-    decoding_errors: str
-    def __init__(
-        self,
-        stream=None,
-        encoding: str | None = None,
-        encoding_errors: str = "backslashreplace",
-        decoding_errors: str = "replace",
-    ) -> None: ...
-    def write(self, data: _DataType) -> None: ...
-    def close(self) -> None: ...
diff --git a/stubs/docutils/docutils/utils/math/__init__.pyi b/stubs/docutils/docutils/utils/math/__init__.pyi
index 3504ef1438fe..cfe920e0bbc7 100644
--- a/stubs/docutils/docutils/utils/math/__init__.pyi
+++ b/stubs/docutils/docutils/utils/math/__init__.pyi
@@ -1,7 +1,9 @@
-from typing import Literal
+from typing import Final, Literal
 
 from docutils.nodes import Node
 
+__docformat__: Final = "reStructuredText"
+
 class MathError(ValueError):
     details: list[Node]
     def __init__(self, msg: object, details: list[Node] = []) -> None: ...
diff --git a/stubs/docutils/docutils/utils/math/math2html.pyi b/stubs/docutils/docutils/utils/math/math2html.pyi
index c2373eb319ef..0972842a9ad0 100644
--- a/stubs/docutils/docutils/utils/math/math2html.pyi
+++ b/stubs/docutils/docutils/utils/math/math2html.pyi
@@ -4,6 +4,7 @@ from typing import ClassVar, Final, TextIO, TypeVar
 
 _T = TypeVar("_T")
 
+__docformat__: Final = "reStructuredText"
 __version__: Final[str]
 
 class Trace:
@@ -88,7 +89,7 @@ class ContainerExtractor:
     extracted: Incomplete
     def __init__(self, config) -> None: ...
     def extract(self, container): ...
-    def process(self, container, list) -> None: ...
+    def process(self, container, lst) -> None: ...
     def safeclone(self, container): ...
 
 class Parser:
diff --git a/stubs/docutils/docutils/utils/math/mathml_elements.pyi b/stubs/docutils/docutils/utils/math/mathml_elements.pyi
index 3f1c4d803a3d..a3aef8ac2cda 100644
--- a/stubs/docutils/docutils/utils/math/mathml_elements.pyi
+++ b/stubs/docutils/docutils/utils/math/mathml_elements.pyi
@@ -4,6 +4,7 @@ from collections.abc import Iterable
 from typing import ClassVar, Final, SupportsIndex, overload
 from typing_extensions import Self
 
+__docformat__: Final = "reStructuredText"
 GLOBAL_ATTRIBUTES: Final[tuple[str, ...]]
 
 class MathElement(ET.Element):
diff --git a/stubs/docutils/docutils/utils/math/tex2mathml_extern.pyi b/stubs/docutils/docutils/utils/math/tex2mathml_extern.pyi
index d0efc08b1dd9..c15fde2125f9 100644
--- a/stubs/docutils/docutils/utils/math/tex2mathml_extern.pyi
+++ b/stubs/docutils/docutils/utils/math/tex2mathml_extern.pyi
@@ -1,5 +1,6 @@
 from typing import Final
 
+__docformat__: Final = "reStructuredText"
 document_template: Final[str]
 
 def blahtexml(math_code: str, as_block: bool = False) -> str: ...
diff --git a/stubs/docutils/docutils/utils/roman.pyi b/stubs/docutils/docutils/utils/roman.pyi
deleted file mode 100644
index 877a52a4a9ac..000000000000
--- a/stubs/docutils/docutils/utils/roman.pyi
+++ /dev/null
@@ -1,23 +0,0 @@
-import argparse
-import re
-from typing import Final, Literal
-
-__author__: Final[str]
-__version__: Final[str]
-__date__: Final[str]
-__copyright__: Final[str]
-
-class RomanError(Exception): ...
-class OutOfRangeError(RomanError): ...
-class NotIntegerError(RomanError): ...
-class InvalidRomanNumeralError(RomanError): ...
-
-romanNumeralMap: tuple[tuple[str, int], ...]
-
-def toRoman(n: int) -> str: ...
-
-romanNumeralPattern: Final[re.Pattern[str]]
-
-def fromRoman(s: str) -> int: ...
-def parse_args() -> argparse.Namespace: ...
-def main() -> Literal[0]: ...
diff --git a/stubs/docutils/docutils/writers/__init__.pyi b/stubs/docutils/docutils/writers/__init__.pyi
index 7934fd8b4190..3fa0f555d1ae 100644
--- a/stubs/docutils/docutils/writers/__init__.pyi
+++ b/stubs/docutils/docutils/writers/__init__.pyi
@@ -1,7 +1,10 @@
+from _typeshed import StrPath
+from pathlib import Path
 from typing import Any, Final, Generic, TypedDict, TypeVar, type_check_only
 from typing_extensions import Required
 
 from docutils import Component, nodes
+from docutils.frontend import Values
 from docutils.io import Output
 from docutils.languages import LanguageImporter
 
@@ -79,4 +82,11 @@ class Writer(Component, Generic[_S]):
 
 class UnfilteredWriter(Writer[_S]): ...
 
+class DoctreeTranslator(nodes.NodeVisitor):
+    settings: Values
+    def __init__(self, document: nodes.document) -> None: ...
+    def uri2path(self, uri: str, output_path: StrPath | None = None) -> Path: ...
+
+WRITER_ALIASES: Final[dict[str, str]]
+
 def get_writer_class(writer_name: str) -> type[Writer[Any]]: ...
diff --git a/stubs/docutils/docutils/writers/_html_base.pyi b/stubs/docutils/docutils/writers/_html_base.pyi
index 247acb75e4f9..9169869aa1a8 100644
--- a/stubs/docutils/docutils/writers/_html_base.pyi
+++ b/stubs/docutils/docutils/writers/_html_base.pyi
@@ -1,12 +1,14 @@
 from _typeshed import Incomplete, StrPath
 from collections.abc import Callable
 from re import Pattern
-from typing import ClassVar, NoReturn
+from typing import ClassVar, Final, NoReturn
 
 from docutils import nodes, writers
 from docutils.frontend import Values
 from docutils.languages import _LanguageModule
 
+__docformat__: Final = "reStructuredText"
+
 class Writer(writers.Writer[str]):
     settings_defaults: ClassVar[dict[str, str]]
     relative_path_settings: ClassVar[tuple[str, ...]]
@@ -79,13 +81,13 @@ class HTMLTranslator(nodes.NodeVisitor):
     def cloak_mailto(self, uri: str) -> str: ...
     def encode(self, text: object) -> str: ...
     def image_size(self, node: nodes.image) -> str: ...
-    def prepare_svg(self, node: nodes.image, imagedata: bytes | bytearray, size_declaration: str | None) -> str: ...
+    def read_size_with_PIL(self, node) -> tuple[int, int] | None: ...
+    def prepare_svg(self, code: str | bytes, node: nodes.Element, atts: dict[str, Incomplete]) -> str: ...
     def stylesheet_call(self, path: StrPath, adjust_path: bool | None = None) -> str: ...
     def starttag(self, node: nodes.Element, tagname: str, suffix: str = "\n", empty: bool = False, **attributes) -> str: ...
     def emptytag(self, node: nodes.Element, tagname: str, suffix: str = "\n", **attributes) -> str: ...
     def report_messages(self, node: nodes.Node) -> None: ...
     def set_class_on_child(self, node, class_, index: int = 0) -> None: ...
-    def uri2imagepath(self, uri: str) -> str: ...
     def visit_Text(self, node: nodes.Text) -> None: ...
     def depart_Text(self, node: nodes.Text) -> None: ...
     def visit_abbreviation(self, node: nodes.abbreviation) -> None: ...
diff --git a/stubs/docutils/docutils/writers/latex2e/__init__.pyi b/stubs/docutils/docutils/writers/latex2e/__init__.pyi
index d91c7d6952c0..aa2378805c0b 100644
--- a/stubs/docutils/docutils/writers/latex2e/__init__.pyi
+++ b/stubs/docutils/docutils/writers/latex2e/__init__.pyi
@@ -1,9 +1,9 @@
 import re
-from _typeshed import Incomplete, StrPath, Unused
+from _typeshed import Incomplete, StrPath
 from collections.abc import Callable, Iterable
 from io import TextIOWrapper
 from pathlib import Path
-from typing import ClassVar, Final, Literal, NoReturn, TypeVar
+from typing import ClassVar, Final, Literal, NoReturn, TypeVar, overload
 from typing_extensions import deprecated
 
 from docutils import nodes
@@ -47,11 +47,13 @@ class Babel:
     def language_name(self, language_code: str) -> str: ...
     def get_language(self) -> str: ...
 
+@deprecated("Deprecated and will be removed in Docutils 0.24.")
 class SortableDict(dict[_K, _V]):
     def sortedkeys(self) -> list[_K]: ...
     def sortedvalues(self) -> list[_V]: ...
 
 class PreambleCmds:
+    ch: ClassVar[str]
     color: ClassVar[str]
     float: ClassVar[str]
     linking: ClassVar[str]
@@ -87,6 +89,9 @@ class PreambleCmds:
     titlereference: ClassVar[str]
     transition: ClassVar[str]
     secnumdepth: ClassVar[str]
+    rem: ClassVar[str]
+    vmin: ClassVar[str]
+    vmax: ClassVar[str]
 
 fp: TextIOWrapper
 line: str
@@ -129,8 +134,6 @@ class Table:
     def get_colspecs(self, node: nodes.Element) -> str: ...
     def get_column_width(self) -> str: ...
     def get_multicolumn_width(self, start: int, len_: int) -> str: ...
-    @deprecated("`writers.latex2e.Table.get_caption()` is obsolete and will be removed in Docutils 0.22.")
-    def get_caption(self) -> str: ...
     def need_recurse(self) -> bool | Literal[0]: ...
     def visit_thead(self) -> list[str]: ...
     def depart_thead(self) -> list[str]: ...
@@ -155,6 +158,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
     insert_newline: ClassVar[bool]
     literal: ClassVar[bool]
     alltt: ClassVar[bool]
+    TITLEDATA_NODES: ClassVar[tuple[type[nodes.Element], ...]]
 
     warn: Callable[..., nodes.system_message]
     error: Callable[..., nodes.system_message]
@@ -217,6 +221,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
     def append_hypertargets(self, node: nodes.Element) -> None: ...
     def set_align_from_classes(self, node) -> None: ...
     def insert_align_declaration(self, node: nodes.Element, default: str | None = None) -> None: ...
+    def provide_fallback(self, feature: str, key: str | None = None) -> None: ...
     def duclass_open(self, node) -> None: ...
     def duclass_close(self, node) -> None: ...
     def push_output_collector(self, new_out) -> None: ...
@@ -280,7 +285,11 @@ class LaTeXTranslator(nodes.NodeVisitor):
     def depart_description(self, node: nodes.description) -> None: ...
     def visit_docinfo(self, node: nodes.docinfo) -> None: ...
     def depart_docinfo(self, node: nodes.docinfo) -> None: ...
-    def visit_docinfo_item(self, node, name: str) -> None: ...
+    @overload
+    def visit_docinfo_item(self, node, name: None = None) -> None: ...
+    @overload
+    @deprecated("The `name` parameter is deprecated and will be removed in Docutils 0.24.")
+    def visit_docinfo_item(self, node, name: str = ...) -> None: ...
     def depart_docinfo_item(self, node) -> None: ...
     def visit_doctest_block(self, node: nodes.doctest_block) -> None: ...
     def depart_doctest_block(self, node: nodes.doctest_block) -> None: ...
@@ -320,7 +329,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
     def depart_generated(self, node: nodes.generated) -> None: ...
     def visit_header(self, node: nodes.header) -> None: ...
     def depart_header(self, node: nodes.header) -> None: ...
-    def to_latex_length(self, length_str: str, pxunit: Unused = None) -> str: ...
+    def to_latex_length(self, length_str: str, node: nodes.Node | None = None) -> str: ...
     def visit_image(self, node: nodes.image) -> None: ...
     def depart_image(self, node: nodes.image) -> None: ...
     def visit_inline(self, node: nodes.inline) -> None: ...
diff --git a/stubs/docutils/docutils/writers/manpage.pyi b/stubs/docutils/docutils/writers/manpage.pyi
index 192cfa43b93b..6eb88a13c497 100644
--- a/stubs/docutils/docutils/writers/manpage.pyi
+++ b/stubs/docutils/docutils/writers/manpage.pyi
@@ -19,6 +19,11 @@ OPTION_LIST_INDENT: Final[int]
 BLOCKQOUTE_INDENT: Final[float]
 LITERAL_BLOCK_INDENT: Final[float]
 MACRO_DEF: Final[str]
+NONPRINTING_BREAKPOINT: Final[str]
+NONBREAKING_INSERT_RE: Final[re.Pattern[str]]
+NONBREAKING_INSERT_RE2: Final[re.Pattern[str]]
+
+def insert_URI_breakpoints(s: str) -> str: ...
 
 class Writer(writers.Writer[str]):
     translator_class: type[Translator]
@@ -51,8 +56,10 @@ class Translator(nodes.NodeVisitor):
     def comment_begin(self, text: str) -> str: ...
     def comment(self, text: str) -> str: ...
     def ensure_eol(self) -> None: ...
+    def ensure_c_eol(self) -> None: ...
     def astext(self) -> str: ...
     def deunicode(self, text: str) -> str: ...
+    def encode_special_chars(self, text: str) -> str: ...
     def visit_Text(self, node: nodes.Text) -> None: ...
     def depart_Text(self, node: nodes.Text) -> None: ...
     def list_start(self, node) -> None: ...
@@ -198,8 +205,6 @@ class Translator(nodes.NodeVisitor):
     def visit_problematic(self, node: nodes.problematic) -> None: ...
     def depart_problematic(self, node: nodes.problematic) -> None: ...
     def visit_raw(self, node: nodes.raw) -> None: ...
-    def visit_reference(self, node: nodes.reference) -> None: ...
-    def depart_reference(self, node: nodes.reference) -> None: ...
     def visit_revision(self, node: nodes.revision) -> None: ...
     def depart_revision(self, node: nodes.revision) -> None: ...
     def visit_row(self, node: nodes.row) -> None: ...
diff --git a/stubs/docutils/docutils/writers/null.pyi b/stubs/docutils/docutils/writers/null.pyi
index befd12f780ef..f20c030b833c 100644
--- a/stubs/docutils/docutils/writers/null.pyi
+++ b/stubs/docutils/docutils/writers/null.pyi
@@ -1,7 +1,9 @@
-from typing import ClassVar
+from typing import ClassVar, Final
 
 from docutils import writers
 
+__docformat__: Final = "reStructuredText"
+
 class Writer(writers.UnfilteredWriter[str]):
     supported: ClassVar[tuple[str, ...]]
     config_section: ClassVar[str]
diff --git a/stubs/docutils/docutils/writers/odf_odt/__init__.pyi b/stubs/docutils/docutils/writers/odf_odt/__init__.pyi
index e989927b332c..d9a6795a9438 100644
--- a/stubs/docutils/docutils/writers/odf_odt/__init__.pyi
+++ b/stubs/docutils/docutils/writers/odf_odt/__init__.pyi
@@ -90,7 +90,9 @@ class Writer(writers.Writer[bytes]):
     visitor: ODFTranslator
     def assemble_my_parts(self) -> None: ...
     def update_stylesheet(self, stylesheet_root, language_code: str | None, region_code: str | None): ...
-    def write_zip_str(self, zfile: zipfile.ZipFile, name: str, bytes: str | SizedBuffer, compress_type: int = 8) -> None: ...
+    def write_zip_str(
+        self, zfile: zipfile.ZipFile, name: str, bytes_: str | SizedBuffer, compress_type: int = zipfile.ZIP_DEFLATED
+    ) -> None: ...
     def store_embedded_files(self, zfile: zipfile.ZipFile) -> None: ...
     def get_settings(self) -> bytes: ...
     def get_stylesheet(self) -> bytes: ...
diff --git a/stubs/docutils/docutils/writers/xetex/__init__.pyi b/stubs/docutils/docutils/writers/xetex/__init__.pyi
index 33fd0181a108..a8528b3670b2 100644
--- a/stubs/docutils/docutils/writers/xetex/__init__.pyi
+++ b/stubs/docutils/docutils/writers/xetex/__init__.pyi
@@ -27,3 +27,4 @@ class Babel(latex2e.Babel):
 class XeLaTeXTranslator(latex2e.LaTeXTranslator):
     is_xetex: bool  # type: ignore[misc]
     def __init__(self, document: nodes.document) -> None: ...
+    def to_latex_length(self, length_str: str, node: nodes.Node | None = None) -> str: ...