diff --git a/CHANGES b/CHANGES index 166748ad9e9..f756e2722bb 100644 --- a/CHANGES +++ b/CHANGES @@ -14,6 +14,8 @@ Deprecated ---------- * The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()`` +* The ``no_docstring`` argument of + ``sphinx.ext.autodoc.Documenter.add_content()`` * ``sphinx.ext.autodoc.Documenter.get_object_members()`` * ``sphinx.ext.autodoc.DataDeclarationDocumenter`` * ``sphinx.ext.autodoc.GenericAliasDocumenter`` diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 068bf899b8c..cbdf3135069 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -31,6 +31,12 @@ The following is a list of deprecated interfaces. - 5.0 - N/A + * - The ``no_docstring`` argument of + ``sphinx.ext.autodoc.Documenter.add_content()`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.Documenter.get_doc()`` + * - ``sphinx.ext.autodoc.Documenter.get_object_members()`` - 3.4 - 6.0 diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index b663e4d040b..6f8ec21cbf1 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -584,6 +584,11 @@ def get_sourcename(self) -> str: def add_content(self, more_content: Optional[StringList], no_docstring: bool = False ) -> None: """Add content from docstrings, attribute documentation and user.""" + if no_docstring: + warnings.warn("The 'no_docstring' argument to %s.add_content() is deprecated." + % self.__class__.__name__, + RemovedInSphinx50Warning, stacklevel=2) + # set sourcename and add content from attribute documentation sourcename = self.get_sourcename() if self.analyzer: @@ -1595,6 +1600,10 @@ def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated." % self.__class__.__name__, RemovedInSphinx40Warning, stacklevel=2) + if self.doc_as_attr: + # Don't show the docstring of the class when it is an alias. + return [] + lines = getattr(self, '_new_docstrings', None) if lines is not None: return lines @@ -1641,10 +1650,9 @@ def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def add_content(self, more_content: Optional[StringList], no_docstring: bool = False ) -> None: if self.doc_as_attr: - content = StringList([_('alias of %s') % restify(self.object)], source='') - super().add_content(content, no_docstring=True) - else: - super().add_content(more_content) + more_content = StringList([_('alias of %s') % restify(self.object)], source='') + + super().add_content(more_content) def document_members(self, all_members: bool = False) -> None: if self.doc_as_attr: @@ -1811,13 +1819,11 @@ def should_suppress_value_header(self) -> bool: return (self.object == UNINITIALIZED_ATTR or super().should_suppress_value_header()) - def add_content(self, more_content: Optional[StringList], no_docstring: bool = False - ) -> None: + def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: if self.object is UNINITIALIZED_ATTR: - # suppress docstring of the value - super().add_content(more_content, no_docstring=True) # type: ignore + return [] else: - super().add_content(more_content, no_docstring=no_docstring) # type: ignore + return super().get_doc(encoding, ignore) # type: ignore class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin, @@ -2220,6 +2226,11 @@ def add_directive_header(self, sig: str) -> None: pass def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: + if not self._datadescriptor: + # if it's not a data descriptor, its docstring is very probably the + # wrong thing to display + return [] + try: # Disable `autodoc_inherit_docstring` temporarily to avoid to obtain # a docstring from the value which descriptor returns unexpectedly. @@ -2232,11 +2243,6 @@ def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def add_content(self, more_content: Optional[StringList], no_docstring: bool = False ) -> None: - if not self._datadescriptor: - # if it's not a data descriptor, its docstring is very probably the - # wrong thing to display - no_docstring = True - if more_content is None: more_content = StringList() self.update_content(more_content)