Extract _prepare_docstrings() (#13977)

Author: AA-Turner

sphinx/ext/autodoc/_docstrings.py

@@ -16,9 +16,11 @@
 from sphinx.util.inspect import getdoc
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Iterator, Mapping, Sequence
     from typing import Any, Literal
 
+    from sphinx.events import EventManager
+    from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
     from sphinx.ext.autodoc._property_types import _ItemProperties
     from sphinx.ext.autodoc.importer import _AttrGetter
 
@@ -28,6 +30,76 @@
 _OBJECT_NEW_DOCSTRING = (tuple(prepare_docstring(object.__new__.__doc__ or '')),)
 
 
+def _prepare_docstrings(
+    *,
+    props: _ItemProperties,
+    attr_docs: Mapping[tuple[str, str], list[str]],
+) -> list[list[str]] | None:
+    """Add content from docstrings, attribute documentation and user."""
+    if props._docstrings is not None:
+        if props._docstrings:
+            docstrings = [list(doc) for doc in props._docstrings]
+        else:
+            # append at least a dummy docstring, so that the event
+            # autodoc-process-docstring is fired and can add some
+            # content if desired
+            docstrings = [[]]
+    else:
+        docstrings = None
+
+    if props.obj_type in {'data', 'attribute'}:
+        return docstrings
+
+    if props.obj_type in {'class', 'exception'}:
+        real_module = props._obj___module__ or props.module_name
+        if props.module_name != real_module:
+            try:
+                # override analyzer to obtain doc-comment around its definition.
+                ma = ModuleAnalyzer.for_module(props.module_name)
+                ma.analyze()
+                attr_docs = ma.attr_docs
+            except PycodeError:
+                pass
+
+    # add content from attribute documentation
+    if attr_docs and props.parts:
+        key = ('.'.join(props.parent_names), props.name)
+        if key in attr_docs:
+            # make a copy of docstring for attributes to avoid cache
+            # the change of autodoc-process-docstring event.
+            return [list(attr_docs[key])]
+
+    return docstrings
+
+
+def _process_docstrings(
+    docstrings: list[list[str]] | None,
+    *,
+    events: EventManager,
+    props: _ItemProperties,
+    obj: Any,
+    options: _AutoDocumenterOptions,
+) -> Iterator[str]:
+    """Let the user process the docstrings before adding them."""
+    if docstrings is None:
+        return
+    for docstring_lines in docstrings:
+        # let extensions pre-process docstrings
+        events.emit(
+            'autodoc-process-docstring',
+            props.obj_type,
+            props.full_name,
+            obj,
+            options,
+            docstring_lines,
+        )
+
+        yield from docstring_lines
+        if docstring_lines and docstring_lines[-1]:
+            # ensure the docstring ends with a blank line
+            yield ''
+
+
 def _get_docstring_lines(
     props: _ItemProperties,
     *,

sphinx/ext/autodoc/_documenters.py

@@ -16,6 +16,7 @@
     member_order_option,
     members_option,
 )
+from sphinx.ext.autodoc._docstrings import _prepare_docstrings, _process_docstrings
 from sphinx.ext.autodoc._member_finder import _document_members
 from sphinx.ext.autodoc._renderer import _add_content, _directive_header_lines
 from sphinx.ext.autodoc.importer import _load_object_by_name
@@ -27,7 +28,7 @@
 from sphinx.util.typing import restify, stringify_annotation
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator, Sequence
+    from collections.abc import Callable, Sequence
     from typing import Any, ClassVar, Final, Literal, NoReturn
 
     from sphinx.config import Config
@@ -181,12 +182,13 @@ def add_directive_header(self, *, indent: str) -> None:
 
     def add_content(self, more_content: StringList | None, *, indent: str) -> None:
         """Add content from docstrings, attribute documentation and user."""
-        analyzer_source = '' if self.analyzer is None else self.analyzer.srcname
         # add content from docstrings
+        attr_docs = {} if self.analyzer is None else self.analyzer.attr_docs
+        analyzer_source = '' if self.analyzer is None else self.analyzer.srcname
         processed_doc = StringList(
             list(
-                self._process_docstrings(
-                    self._get_docstrings(),
+                _process_docstrings(
+                    _prepare_docstrings(props=self.props, attr_docs=attr_docs),
                     events=self._events,
                     props=self.props,
                     obj=self.props._obj,
@@ -214,74 +216,6 @@ def add_content(self, more_content: StringList | None, *, indent: str) -> None:
             indent=indent + '   ' * (self.props.obj_type != 'module'),
         )
 
-    def _get_docstrings(self) -> list[list[str]] | None:
-        """Add content from docstrings, attribute documentation and user."""
-        if self.props._docstrings is not None:
-            docstrings = [list(doc) for doc in self.props._docstrings]
-        else:
-            docstrings = None
-        props = self.props
-
-        if docstrings is not None and len(docstrings) == 0:
-            # append at least a dummy docstring, so that the event
-            # autodoc-process-docstring is fired and can add some
-            # content if desired
-            docstrings.append([])
-
-        if props.obj_type in {'data', 'attribute'}:
-            return docstrings
-
-        attr_docs = None if self.analyzer is None else self.analyzer.find_attr_docs()
-        if props.obj_type in {'class', 'exception'}:
-            real_module = props._obj___module__ or props.module_name
-            if props.module_name != real_module:
-                try:
-                    # override analyzer to obtain doc-comment around its definition.
-                    ma = ModuleAnalyzer.for_module(props.module_name)
-                    ma.analyze()
-                    attr_docs = ma.attr_docs
-                except PycodeError:
-                    pass
-
-        # add content from attribute documentation
-        if attr_docs is not None and props.parts:
-            key = ('.'.join(props.parent_names), props.name)
-            if key in attr_docs:
-                # make a copy of docstring for attributes to avoid cache
-                # the change of autodoc-process-docstring event.
-                return [list(attr_docs[key])]
-
-        return docstrings
-
-    @staticmethod
-    def _process_docstrings(
-        docstrings: list[list[str]] | None,
-        *,
-        events: EventManager,
-        props: _ItemProperties,
-        obj: Any,
-        options: _AutoDocumenterOptions,
-    ) -> Iterator[str]:
-        """Let the user process the docstrings before adding them."""
-        if docstrings is None:
-            return
-        for docstring_lines in docstrings:
-            # let extensions preprocess docstrings
-            events.emit(
-                'autodoc-process-docstring',
-                props.obj_type,
-                props.full_name,
-                obj,
-                options,
-                docstring_lines,
-            )
-
-            if docstring_lines and docstring_lines[-1]:
-                # append a blank line to the end of the docstring
-                docstring_lines.append('')
-
-            yield from docstring_lines
-
     @staticmethod
     def _assemble_more_content(
         more_content: StringList,