Extract the _docstring_source_name() function (#13972)

Author: AA-Turner

doc/development/tutorials/examples/autodoc_intenum.py

@@ -4,6 +4,7 @@
 from typing import TYPE_CHECKING
 
 from sphinx.ext.autodoc import ClassDocumenter, bool_option
+from sphinx.ext.autodoc._documenters import _docstring_source_name
 
 if TYPE_CHECKING:
     from typing import Any
@@ -31,27 +32,33 @@ def can_document_member(
         except TypeError:
             return False
 
+    def add_line(self, line: str, source: str = '', *lineno: int, indent: str) -> None:
+        """Append one line of generated reST to the output."""
+        analyzer_source = '' if self.analyzer is None else self.analyzer.srcname
+        source_name = _docstring_source_name(props=self.props, source=analyzer_source)
+        if line.strip():  # not a blank line
+            self.directive.result.append(indent + line, source_name, *lineno)
+        else:
+            self.directive.result.append('', source_name, *lineno)
+
     def add_directive_header(self, *, indent: str) -> None:
         super().add_directive_header(indent=indent)
-        self.add_line('   :final:', self.get_sourcename(), indent=indent)
+        self.add_line('   :final:', indent=indent)
 
     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, indent=indent)
+        self.add_line('', 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, indent=indent
-            )
-            self.add_line('', source_name, indent=indent)
+            self.add_line(f'**{the_member_name}**: {the_member_value}', indent=indent)
+            self.add_line('', indent=indent)
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

sphinx/ext/autodoc/_documenters.py

@@ -167,7 +167,8 @@ def add_directive_header(self, *, indent: str) -> None:
             is_final = False
 
         result = self.directive.result
-        sourcename = self.get_sourcename()
+        analyzer_source = '' if self.analyzer is None else self.analyzer.srcname
+        source_name = _docstring_source_name(props=self.props, source=analyzer_source)
         for line in _directive_header_lines(
             autodoc_typehints=self.config.autodoc_typehints,
             directive_name=directive_name,
@@ -176,27 +177,13 @@ def add_directive_header(self, *, indent: str) -> None:
             props=self.props,
         ):
             if line.strip():  # not a blank line
-                result.append(indent + line, sourcename)
+                result.append(indent + line, source_name)
             else:
-                result.append('', sourcename)
-
-    def get_sourcename(self) -> str:
-        obj_module = inspect.safe_getattr(self.props._obj, '__module__', None)
-        obj_qualname = inspect.safe_getattr(self.props._obj, '__qualname__', None)
-        if obj_module and obj_qualname:
-            # Get the correct location of docstring from props._obj
-            # to support inherited methods
-            fullname = f'{self.props._obj.__module__}.{self.props._obj.__qualname__}'
-        else:
-            fullname = self.props.full_name
-
-        if self.analyzer:
-            return f'{self.analyzer.srcname}:docstring of {fullname}'
-        else:
-            return 'docstring of %s' % fullname
+                result.append('', source_name)
 
     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
         processed_doc = StringList(
             list(
@@ -208,7 +195,7 @@ def add_content(self, more_content: StringList | None, *, indent: str) -> None:
                     options=self.options,
                 )
             ),
-            source=self.get_sourcename(),
+            source=_docstring_source_name(props=self.props, source=analyzer_source),
         )
         _add_content(
             processed_doc,
@@ -451,16 +438,17 @@ def _generate(
                 return
 
         indent = self.indent
-        sourcename = self.get_sourcename()
+        analyzer_source = '' if self.analyzer is None else self.analyzer.srcname
+        source_name = _docstring_source_name(props=self.props, source=analyzer_source)
 
         # 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.directive.result.append('', sourcename)
+        self.directive.result.append('', source_name)
 
         # generate the directive header and options, if applicable
         self.add_directive_header(indent=indent)
-        self.directive.result.append('', sourcename)
+        self.directive.result.append('', source_name)
 
         # add all content (from docstrings, attribute docs etc.)
         self.add_content(more_content, indent=indent)
@@ -643,3 +631,18 @@ def __setattr__(self, key: str, value: Any) -> NoReturn:
     def __delattr__(self, key: str) -> NoReturn:
         msg = f'{self.__class__.__name__} is immutable'
         raise AttributeError(msg)
+
+
+def _docstring_source_name(*, props: _ItemProperties, source: str) -> str:
+    obj_module = inspect.safe_getattr(props._obj, '__module__', None)
+    obj_qualname = inspect.safe_getattr(props._obj, '__qualname__', None)
+    if obj_module and obj_qualname:
+        # Get the correct location of docstring from props._obj
+        # to support inherited methods
+        fullname = f'{obj_module}.{obj_qualname}'
+    else:
+        fullname = props.full_name
+
+    if source:
+        return f'{source}:docstring of {fullname}'
+    return f'docstring of {fullname}'