Treat Documenter.indent as a constant (#13960)

Author: AA-Turner

doc/development/tutorials/examples/autodoc_intenum.py

@@ -31,28 +31,27 @@ def can_document_member(
         except TypeError:
             return False
 
-    def add_directive_header(self) -> None:
-        super().add_directive_header()
-        self.add_line('   :final:', self.get_sourcename())
+    def add_directive_header(self, *, indent: str) -> None:
+        super().add_directive_header(indent=indent)
+        self.add_line('   :final:', self.get_sourcename(), indent=indent)
 
-    def add_content(
-        self,
-        more_content: StringList | None,
-    ) -> None:
-        super().add_content(more_content)
+    def add_content(self, more_content: StringList | None, *, indent: str) -> None:
+        super().add_content(more_content, indent=indent)
 
         source_name = self.get_sourcename()
         enum_object: IntEnum = self.props._obj
         use_hex = self.options.hex
-        self.add_line('', source_name)
+        self.add_line('', source_name, indent=indent)
 
         for the_member_name, enum_member in enum_object.__members__.items():  # type: ignore[attr-defined]
             the_member_value = enum_member.value
             if use_hex:
                 the_member_value = hex(the_member_value)
 
-            self.add_line(f'**{the_member_name}**: {the_member_value}', source_name)
-            self.add_line('', source_name)
+            self.add_line(
+                f'**{the_member_name}**: {the_member_value}', source_name, indent=indent
+            )
+            self.add_line('', source_name, indent=indent)
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

sphinx/ext/autodoc/_documenters.py

@@ -30,7 +30,7 @@
 if TYPE_CHECKING:
     from collections.abc import Iterator
     from types import ModuleType
-    from typing import Any, ClassVar, Literal
+    from typing import Any, ClassVar, Final, Literal
 
     from sphinx.config import Config
     from sphinx.environment import BuildEnvironment, _CurrentDocument
@@ -79,8 +79,6 @@ class Documenter:
     #: name by which the directive is called (auto...) and the default
     #: generated directive name
     objtype: ClassVar = 'object'
-    #: indentation by which to indent the directive content
-    content_indent: ClassVar = '   '
     #: order if autodoc_member_order is set to 'groupwise'
     member_order: ClassVar = 0
     #: true if the generated content may contain titles
@@ -109,7 +107,7 @@ def __init__(
         self._events: EventManager = directive.env.events
         self.options: _AutoDocumenterOptions = directive.genopt
         self.name = name
-        self.indent = indent
+        self.indent: Final = indent
         # the module and object path within the module, and the fully
         # qualified name (all set after resolve_name succeeds)
         self.modname: str = ''
@@ -141,10 +139,10 @@ def documenters(self) -> dict[str, type[Documenter]]:
         """Returns registered Documenter classes"""
         return self.env._registry.documenters
 
-    def add_line(self, line: str, source: str, *lineno: int) -> None:
+    def add_line(self, line: str, source: str, *lineno: int, indent: str) -> None:
         """Append one line of generated reST to the output."""
         if line.strip():  # not a blank line
-            self.directive.result.append(self.indent + line, source, *lineno)
+            self.directive.result.append(indent + line, source, *lineno)
         else:
             self.directive.result.append('', source, *lineno)
 
@@ -278,7 +276,7 @@ def _call_format_args(self, **kwargs: Any) -> str:
         # retry without arguments for old documenters
         return self.format_args()
 
-    def add_directive_header(self) -> None:
+    def add_directive_header(self, *, indent: str) -> None:
         """Add the directive header and options to the generated content."""
         domain_name = getattr(self, 'domain', 'py')
         if self.objtype in {'class', 'exception'} and self.props.doc_as_attr:  # type: ignore[attr-defined]
@@ -292,7 +290,6 @@ def add_directive_header(self) -> None:
         else:
             is_final = False
 
-        indent = self.indent
         result = self.directive.result
         sourcename = self.get_sourcename()
         for line in _directive_header_lines(
@@ -322,7 +319,7 @@ def get_sourcename(self) -> str:
         else:
             return 'docstring of %s' % fullname
 
-    def add_content(self, more_content: StringList | None) -> None:
+    def add_content(self, more_content: StringList | None, *, indent: str) -> None:
         """Add content from docstrings, attribute documentation and user."""
         # add content from docstrings
         processed_doc = StringList(
@@ -340,7 +337,7 @@ def add_content(self, more_content: StringList | None) -> None:
         _add_content(
             processed_doc,
             result=self.directive.result,
-            indent=self.indent + '   ' * (self.props.obj_type == 'module'),
+            indent=indent + '   ',
         )
 
         # add additional content (e.g. from document), if present
@@ -353,7 +350,7 @@ def add_content(self, more_content: StringList | None) -> None:
         _add_content(
             more_content,
             result=self.directive.result,
-            indent=self.indent,
+            indent=indent + '   ' * (self.props.obj_type != 'module'),
         )
 
     def _get_docstrings(self) -> list[list[str]] | None:
@@ -569,10 +566,6 @@ def _generate(
         check_module: bool = False,
         all_members: bool = False,
     ) -> None:
-        has_members = isinstance(self, ModuleDocumenter) or (
-            isinstance(self, ClassDocumenter) and not self.props.doc_as_attr
-        )
-
         # If there is no real module defined, figure out which to use.
         # The real module is used in the module analyzer to look up the module
         # where the attribute documentation would actually be found in.
@@ -597,14 +590,6 @@ def _generate(
         else:
             self.directive.record_dependencies.add(self.analyzer.srcname)
 
-        want_all = bool(
-            all_members or self.options.inherited_members or self.options.members is ALL
-        )
-        if has_members:
-            member_documenters = self._gather_members(
-                want_all=want_all, indent=self.indent + self.content_indent
-            )
-
         if self.real_modname != guess_modname:
             # Add module to dependency list if target object is defined in other module.
             try:
@@ -629,25 +614,32 @@ def _generate(
             if modname and modname != self.props.module_name:
                 return
 
+        indent = self.indent
         sourcename = self.get_sourcename()
 
         # make sure that the result starts with an empty line.  This is
         # necessary for some situations where another directive preprocesses
         # reST and no starting newline is present
-        self.add_line('', sourcename)
+        self.directive.result.append('', sourcename)
 
         # generate the directive header and options, if applicable
-        self.add_directive_header()
-        self.add_line('', sourcename)
-
-        # e.g. the module directive doesn't have content
-        self.indent += self.content_indent
+        self.add_directive_header(indent=indent)
+        self.directive.result.append('', sourcename)
 
         # add all content (from docstrings, attribute docs etc.)
-        self.add_content(more_content)
+        self.add_content(more_content, indent=indent)
 
         # document members, if possible
+        has_members = isinstance(self, ModuleDocumenter) or (
+            isinstance(self, ClassDocumenter) and not self.props.doc_as_attr
+        )
         if has_members:
+            want_all = bool(
+                all_members
+                or self.options.inherited_members
+                or self.options.members is ALL
+            )
+            member_documenters = self._gather_members(want_all=want_all, indent=indent)
             # for implicit module members, check __module__ to avoid
             # documenting imported objects
             members_check_module = bool(
@@ -677,6 +669,7 @@ def _gather_members(
         events = self._events
         registry = self.env._registry
         props = self.props
+        indent += '   ' * (props.obj_type != 'module')
 
         # set current namespace for finding members
         current_document.autodoc_module = props.module_name
@@ -759,8 +752,6 @@ class ModuleDocumenter(Documenter):
     props: _ModuleProperties
 
     objtype = 'module'
-    content_indent = ''
-    _extra_indent = '   '
 
     option_spec: ClassVar[OptionSpec] = {
         'members': members_option,

sphinx/ext/autosummary/__init__.py

@@ -462,11 +462,11 @@ def get_items(self, names: list[str]) -> list[tuple[str, str | None, str, str]]:
 
             # -- Grab the summary
 
-            # bodge for ModuleDocumenter
-            documenter._extra_indent = ''  # type: ignore[attr-defined]
-
-            documenter.add_content(None)
-            summary = extract_summary(self.bridge.result.data[:], self.state.document)
+            documenter.add_content(None, indent=documenter.indent)
+            lines = self.bridge.result.data[:]
+            if documenter.props.obj_type != 'module':
+                lines[:] = [line.removeprefix('   ') for line in lines]
+            summary = extract_summary(lines, self.state.document)
 
             items.append((display_name, sig, summary, real_name))