IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #8589 from tk0miya/8581_deprecate_no_docstrings

Browse Source 
refactor: Deprecate `no_docstring` argument for Documenter.add_content()
This commit is contained in:
Takeshi KOMIYA 2020-12-27 22:19:30 +09:00 committed by GitHub
commit 07983a5a87
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 52 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
sphinx/ext/autodoc/__init__.py
View File

@ -538,8 +538,12 @@ class Documenter:
# etc. don't support a prepended module name # etc. don't support a prepended module name
self.add_line(' :module: %s' % self.modname, sourcename) self.add_line(' :module: %s' % self.modname, sourcename)
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:
"""Decode and return lines of the docstring(s) for the object.""" """Decode and return lines of the docstring(s) for the object.
When it returns None value, autodoc-process-docstring will not be called for this
object.
"""
if encoding is not None: if encoding is not None:
warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated." warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated."
% self.__class__.__name__, % self.__class__.__name__,
@ -587,12 +591,10 @@ class Documenter:
def add_content(self, more_content: Optional[StringList], no_docstring: bool = False def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
) -> None: ) -> None:
"""Add content from docstrings, attribute documentation and user.""" """Add content from docstrings, attribute documentation and user."""
# Suspended temporarily (see https://github.com/sphinx-doc/sphinx/pull/8533) if no_docstring:
# warnings.warn("The 'no_docstring' argument to %s.add_content() is deprecated."
# if no_docstring: % self.__class__.__name__,
# warnings.warn("The 'no_docstring' argument to %s.add_content() is deprecated." RemovedInSphinx50Warning, stacklevel=2)
# % self.__class__.__name__,
# RemovedInSphinx50Warning, stacklevel=2)
# set sourcename and add content from attribute documentation # set sourcename and add content from attribute documentation
sourcename = self.get_sourcename() sourcename = self.get_sourcename()
@ -612,13 +614,17 @@ class Documenter:
# add content from docstrings # add content from docstrings
if not no_docstring: if not no_docstring:
docstrings = self.get_doc() docstrings = self.get_doc()
if not docstrings: if docstrings is None:
# append at least a dummy docstring, so that the event # Do not call autodoc-process-docstring on get_doc() returns None.
# autodoc-process-docstring is fired and can add some pass
# content if desired else:
docstrings.append([]) if not docstrings:
for i, line in enumerate(self.process_doc(docstrings)): # append at least a dummy docstring, so that the event
self.add_line(line, sourcename, i) # autodoc-process-docstring is fired and can add some
# content if desired
docstrings.append([])
for i, line in enumerate(self.process_doc(docstrings)):
self.add_line(line, sourcename, i)
# add additional content (e.g. from document), if present # add additional content (e.g. from document), if present
if more_content: if more_content:
@ -1213,7 +1219,7 @@ class DocstringSignatureMixin:
return result return result
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:
if encoding is not None: if encoding is not None:
warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated." warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated."
% self.__class__.__name__, % self.__class__.__name__,
@ -1611,14 +1617,14 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
else: else:
return False, [convert(m) for m in members.values() if m.class_ == self.object] return False, [convert(m) for m in members.values() if m.class_ == self.object]
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:
if encoding is not None: if encoding is not None:
warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated." warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated."
% self.__class__.__name__, % self.__class__.__name__,
RemovedInSphinx40Warning, stacklevel=2) RemovedInSphinx40Warning, stacklevel=2)
if self.doc_as_attr: if self.doc_as_attr:
# Don't show the docstring of the class when it is an alias. # Don't show the docstring of the class when it is an alias.
return [] return None
lines = getattr(self, '_new_docstrings', None) lines = getattr(self, '_new_docstrings', None)
if lines is not None: if lines is not None:
@ -1667,9 +1673,8 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
) -> None: ) -> None:
if self.doc_as_attr: if self.doc_as_attr:
more_content = StringList([_('alias of %s') % restify(self.object)], source='') more_content = StringList([_('alias of %s') % restify(self.object)], source='')
super().add_content(more_content, no_docstring=True)
else: super().add_content(more_content)
super().add_content(more_content)
def document_members(self, all_members: bool = False) -> None: def document_members(self, all_members: bool = False) -> None:
if self.doc_as_attr: if self.doc_as_attr:
@ -1774,7 +1779,7 @@ class TypeVarMixin(DataDocumenterMixinBase):
return (isinstance(self.object, TypeVar) or return (isinstance(self.object, TypeVar) or
super().should_suppress_directive_header()) super().should_suppress_directive_header())
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:
if ignore is not None: if ignore is not None:
warnings.warn("The 'ignore' argument to autodoc.%s.get_doc() is deprecated." warnings.warn("The 'ignore' argument to autodoc.%s.get_doc() is deprecated."
% self.__class__.__name__, % self.__class__.__name__,
@ -1838,7 +1843,7 @@ class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
return (self.object is UNINITIALIZED_ATTR or return (self.object is UNINITIALIZED_ATTR or
super().should_suppress_value_header()) super().should_suppress_value_header())
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:
if self.object is UNINITIALIZED_ATTR: if self.object is UNINITIALIZED_ATTR:
return [] return []
else: else:
@ -2102,7 +2107,7 @@ class NonDataDescriptorMixin(DataDocumenterMixinBase):
return (inspect.isattributedescriptor(self.object) or return (inspect.isattributedescriptor(self.object) or
super().should_suppress_directive_header()) super().should_suppress_directive_header())
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:
if not inspect.isattributedescriptor(self.object): if not inspect.isattributedescriptor(self.object):
# the docstring of non datadescriptor is very probably the wrong thing # the docstring of non datadescriptor is very probably the wrong thing
# to display # to display
@ -2141,7 +2146,7 @@ class SlotsMixin(DataDocumenterMixinBase):
else: else:
return super().should_suppress_directive_header() return super().should_suppress_directive_header()
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:
if self.object is SLOTSATTR: if self.object is SLOTSATTR:
try: try:
__slots__ = inspect.getslots(self.parent) __slots__ = inspect.getslots(self.parent)
@ -2395,7 +2400,7 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin, # type:
return None return None
def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]: def get_doc(self, encoding: str = None, ignore: int = None) -> Optional[List[List[str]]]:
# Check the attribute has a docstring-comment # Check the attribute has a docstring-comment
comment = self.get_attribute_comment(self.parent, self.objpath[-1]) comment = self.get_attribute_comment(self.parent, self.objpath[-1])
if comment: if comment:

3
tests/roots/test-ext-autodoc/target/classes.py
View File

@ -27,3 +27,6 @@ class Qux:
class Quux(List[Union[int, float]]): class Quux(List[Union[int, float]]):
"""A subclass of List[Union[int, float]]""" """A subclass of List[Union[int, float]]"""
pass pass
Alias = Foo

18
tests/test_ext_autodoc_autoclass.py
View File

@ -173,3 +173,21 @@ def test_show_inheritance_for_subclass_of_generic_type(app):
' A subclass of List[Union[int, float]]', ' A subclass of List[Union[int, float]]',
'', '',
] ]
def test_class_alias(app):
def autodoc_process_docstring(*args):
"""A handler always raises an error.
This confirms this handler is never called for class aliases.
"""
raise
app.connect('autodoc-process-docstring', autodoc_process_docstring)
actual = do_autodoc(app, 'class', 'target.classes.Alias')
assert list(actual) == [
'',
'.. py:attribute:: Alias',
' :module: target.classes',
'',
' alias of :class:`target.classes.Foo`',
]