Improve type annotations in 'docutils.node.document' (#11468)

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -8,7 +8,6 @@ docutils.io.Input.__init__
 docutils.languages.LanguageImporter.__getattr__
 docutils.nodes.Element.__getattr__
 docutils.nodes.GenericNodeVisitor.__getattr__
-docutils.nodes.document.__getattr__
 docutils.nodes.Element.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__
 docutils.parsers.rst.Directive.__getattr__
 docutils.transforms.Transform.__getattr__

stubs/docutils/docutils/nodes.pyi

@@ -2,10 +2,12 @@ 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, Literal, Protocol, SupportsIndex, TypeVar, overload
 from typing_extensions import Self, TypeAlias
 
+from docutils.frontend import Values
 from docutils.transforms import Transform, Transformer
 from docutils.utils import Reporter
 
@@ -178,11 +180,66 @@ class Labeled: ...
 
 # Root Element
 
+_Document: TypeAlias = document
+_Decoration: TypeAlias = decoration
+
 class document(Root, Structural, Element):
-    parent: None
+    current_source: str | None
+    current_line: int | None
+    settings: Values
+    reporter: Reporter
+    indirect_targets: list[target]
+    substitution_defs: dict[str, substitution_definition]
+    substitution_names: dict[str, str]
+    refnames: dict[str, list[Element]]
+    refids: dict[str, list[Element]]
+    nameids: dict[str, str]
+    nametypes: dict[str, bool]
+    ids: dict[str, Element]
+    footnote_refs: dict[str, list[footnote_reference]]
+    citation_refs: dict[str, list[citation_reference]]
+    autofootnotes: list[footnote]
+    autofootnote_refs: list[footnote_reference]
+    symbol_footnotes: list[footnote]
+    symbol_footnote_refs: list[footnote_reference]
+    footnotes: list[footnote]
+    citations: list[citation]
+    autofootnote_start: int
+    symbol_footnote_start: int
+    id_counter: Counter[int]
+    parse_messages: list[system_message]
+    transform_messages: list[system_message]
     transformer: Transformer
-    def __init__(self, settings, reporter: Reporter, rawsource: str = "", *children: Node, **attributes) -> None: ...
-    def __getattr__(self, __name: str) -> Incomplete: ...
+    decoration: decoration | None
+    document: Self
+    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_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: ...
+    def note_explicit_target(self, target: Element, msgnode: Element | None = None) -> None: ...
+    def note_refname(self, node: Element) -> None: ...
+    def note_refid(self, node: Element) -> None: ...
+    def note_indirect_target(self, target: target) -> None: ...
+    def note_anonymous_target(self, target: target) -> None: ...
+    def note_autofootnote(self, footnote: footnote) -> None: ...
+    def note_autofootnote_ref(self, ref: footnote_reference) -> None: ...
+    def note_symbol_footnote(self, footnote: footnote) -> None: ...
+    def note_symbol_footnote_ref(self, ref: footnote_reference) -> None: ...
+    def note_footnote(self, footnote: footnote) -> None: ...
+    def note_footnote_ref(self, ref: footnote_reference) -> None: ...
+    def note_citation(self, citation: citation) -> None: ...
+    def note_citation_ref(self, ref: citation_reference) -> None: ...
+    def note_substitution_def(self, subdef: substitution_definition, def_name: str, msgnode: Element | None = None) -> None: ...
+    def note_substitution_ref(self, subref: substitution_reference, refname: str) -> None: ...
+    def note_pending(self, pending: pending, priority: int | None = None) -> None: ...
+    def note_parse_message(self, message: system_message) -> None: ...
+    def note_transform_message(self, message: system_message) -> None: ...
+    def note_source(self, source: str, offset: int) -> None: ...
+    def copy(self) -> Self: ...
+    def get_decoration(self) -> _Decoration: ...
 
 # Title Elements
 
@@ -333,9 +390,6 @@ class generated(Inline, TextElement): ...
 
 node_class_names: list[str]
 
-# necessary to disambiguate type and field in NodeVisitor
-_Document: TypeAlias = document
-
 class NodeVisitor:
     optional: ClassVar[tuple[str, ...]]
     document: _Document