Skip to content

Commit

Permalink
Merge pull request #10539 from AA-Turner/fix-inherited-attrs
Browse files Browse the repository at this point in the history 
Fix inherited attribute docstrings
  • Loading branch information
@tk0miya
tk0miya committed Jun 13, 2022
2 parents 60775ec + 29edce9 commit d045227
Show file tree
Hide file tree
Showing 6 changed files with 93 additions and 3 deletions.
3 changes: 2 additions & 1 deletion sphinx/ext/autodoc/__init__.py
View file
Expand Up @@ -1670,7 +1670,8 @@ def add_directive_header(self, sig: str) -> None:
self.add_line(' ' + _('Bases: %s') % ', '.join(base_classes), sourcename)

def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:
members = get_class_members(self.object, self.objpath, self.get_attr)
members = get_class_members(self.object, self.objpath, self.get_attr,
self.config.autodoc_inherit_docstrings)
if not want_all:
if not self.options.members:
return False, [] # type: ignore
Expand Down
9 changes: 7 additions & 2 deletions sphinx/ext/autodoc/importer.py
View file
Expand Up @@ -205,8 +205,8 @@ def get_object_members(subject: Any, objpath: List[str], attrgetter: Callable,
return members


def get_class_members(subject: Any, objpath: List[str], attrgetter: Callable
) -> Dict[str, "ObjectMember"]:
def get_class_members(subject: Any, objpath: List[str], attrgetter: Callable,
inherit_docstrings: bool = True) -> Dict[str, "ObjectMember"]:
"""Get members and attributes of target class."""
from sphinx.ext.autodoc import INSTANCEATTR, ObjectMember

Expand Down Expand Up @@ -290,6 +290,11 @@ def get_class_members(subject: Any, objpath: List[str], attrgetter: Callable
elif (ns == qualname and docstring and
isinstance(members[name], ObjectMember) and
not members[name].docstring):
if cls != subject and not inherit_docstrings:
# If we are in the MRO of the class and not the class itself,
# and we do not want to inherit docstrings, then skip setting
# the docstring below
continue
# attribute is already known, because dir(subject) enumerates it.
# But it has no docstring yet
members[name].docstring = '\n'.join(docstring)
Expand Down
3 changes: 3 additions & 0 deletions tests/roots/test-ext-autodoc/target/inheritance.py
View file
@@ -1,4 +1,7 @@
class Base(object):
#: docstring
inheritedattr = None

def inheritedmeth(self):
"""Inherited function."""

Expand Down
8 changes: 8 additions & 0 deletions tests/test_ext_autodoc.py
View file
Expand Up @@ -549,6 +549,7 @@ def test_autodoc_members(app):
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:attribute:: Base.inheritedattr',
' .. py:method:: Base.inheritedclassmeth()',
' .. py:method:: Base.inheritedmeth()',
' .. py:method:: Base.inheritedstaticmeth(cls)'
Expand All @@ -569,6 +570,7 @@ def test_autodoc_members(app):
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:attribute:: Base.inheritedattr',
' .. py:method:: Base.inheritedclassmeth()',
' .. py:method:: Base.inheritedmeth()',
' .. py:method:: Base.inheritedstaticmeth(cls)'
Expand Down Expand Up @@ -601,6 +603,7 @@ def test_autodoc_exclude_members(app):
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:attribute:: Base.inheritedattr',
' .. py:method:: Base.inheritedclassmeth()'
]

Expand All @@ -618,6 +621,7 @@ def test_autodoc_exclude_members(app):
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:attribute:: Base.inheritedattr',
' .. py:method:: Base.inheritedclassmeth()'
]

Expand All @@ -628,6 +632,7 @@ def test_autodoc_exclude_members(app):
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:attribute:: Base.inheritedattr',
' .. py:method:: Base.inheritedclassmeth()',
' .. py:method:: Base.inheritedstaticmeth(cls)'
]
Expand All @@ -639,6 +644,7 @@ def test_autodoc_exclude_members(app):
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:attribute:: Base.inheritedattr',
' .. py:method:: Base.inheritedclassmeth()',
]

Expand All @@ -648,6 +654,7 @@ def test_autodoc_exclude_members(app):
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:attribute:: Base.inheritedattr',
' .. py:method:: Base.inheritedclassmeth()',
]

Expand All @@ -658,6 +665,7 @@ def test_autodoc_exclude_members(app):
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:attribute:: Base.inheritedattr',
' .. py:method:: Base.inheritedclassmeth()',
' .. py:method:: Base.inheritedmeth()',
' .. py:method:: Base.inheritedstaticmeth(cls)'
Expand Down
7 changes: 7 additions & 0 deletions tests/test_ext_autodoc_automodule.py
View file
Expand Up @@ -133,6 +133,13 @@ def test_automodule_inherited_members(app):
' :module: target.inheritance',
'',
'',
' .. py:attribute:: Base.inheritedattr',
' :module: target.inheritance',
' :value: None',
'',
' docstring',
'',
'',
' .. py:method:: Base.inheritedclassmeth()',
' :module: target.inheritance',
' :classmethod:',
Expand Down
66 changes: 66 additions & 0 deletions tests/test_ext_autodoc_configs.py
View file
Expand Up @@ -277,6 +277,72 @@ def test_autodoc_inherit_docstrings(app):
]


@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_autodoc_inherit_docstrings_for_inherited_members(app):
options = {"members": None,
"inherited-members": None}

assert app.config.autodoc_inherit_docstrings is True # default
actual = do_autodoc(app, 'class', 'target.inheritance.Derived', options)
assert list(actual) == [
'',
'.. py:class:: Derived()',
' :module: target.inheritance',
'',
'',
' .. py:attribute:: Derived.inheritedattr',
' :module: target.inheritance',
' :value: None',
'',
' docstring',
'',
'',
' .. py:method:: Derived.inheritedclassmeth()',
' :module: target.inheritance',
' :classmethod:',
'',
' Inherited class method.',
'',
'',
' .. py:method:: Derived.inheritedmeth()',
' :module: target.inheritance',
'',
' Inherited function.',
'',
'',
' .. py:method:: Derived.inheritedstaticmeth(cls)',
' :module: target.inheritance',
' :staticmethod:',
'',
' Inherited static method.',
'',
]

# disable autodoc_inherit_docstrings
app.config.autodoc_inherit_docstrings = False
actual = do_autodoc(app, 'class', 'target.inheritance.Derived', options)
assert list(actual) == [
'',
'.. py:class:: Derived()',
' :module: target.inheritance',
'',
'',
' .. py:method:: Derived.inheritedclassmeth()',
' :module: target.inheritance',
' :classmethod:',
'',
' Inherited class method.',
'',
'',
' .. py:method:: Derived.inheritedstaticmeth(cls)',
' :module: target.inheritance',
' :staticmethod:',
'',
' Inherited static method.',
'',
]


@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_autodoc_docstring_signature(app):
options = {"members": None, "special-members": "__init__, __new__"}
Expand Down

0 comments on commit d045227

Please sign in to comment.