ENH: Add support for dict show_inherited_class_members (#415)

* ENH: Add support for dict show_inherited_class_members

* STY: Black

* TST: Add test

Author: larsoner

doc/install.rst

@@ -26,10 +26,18 @@ numpydoc_show_class_members : bool
   Whether to show all members of a class in the Methods and Attributes
   sections automatically.
   ``True`` by default.
-numpydoc_show_inherited_class_members : bool
+numpydoc_show_inherited_class_members : bool | dict
   Whether to show all inherited members of a class in the Methods and Attributes
   sections automatically. If it's false, inherited members won't shown.
-  ``True`` by default.
+  ``True`` by default. It can also be a dict mapping names of classes to
+  boolean values (missing keys are treated as ``True``).
+  For example, ``defaultdict(lambda: False, {'mymod.MyClass': True})``
+  would only show inherited class members for ``MyClass``, whereas
+  ``{'mymod.MyClass': False}`` would show inherited class members for all
+  classes except ``MyClass``. Note that disabling this for a limited set of
+  classes might simultaneously require the use of a separate, custom
+  autosummary class template with ``:no-inherited-members:`` in the
+  ``autoclass`` directive options.
 numpydoc_class_members_toctree : bool
   Whether to create a Sphinx table of contents for the lists of class
   methods and attributes. If a table of contents is made, Sphinx expects

numpydoc/numpydoc.py

@@ -162,12 +162,18 @@ def clean_backrefs(app, doc, docname):
 def mangle_docstrings(app, what, name, obj, options, lines):
     if DEDUPLICATION_TAG in lines:
         return
+    show_inherited_class_members = app.config.numpydoc_show_inherited_class_members
+    if isinstance(show_inherited_class_members, dict):
+        try:
+            show_inherited_class_members = show_inherited_class_members[name]
+        except KeyError:
+            show_inherited_class_members = True
 
     cfg = {
         "use_plots": app.config.numpydoc_use_plots,
         "use_blockquotes": app.config.numpydoc_use_blockquotes,
         "show_class_members": app.config.numpydoc_show_class_members,
-        "show_inherited_class_members": app.config.numpydoc_show_inherited_class_members,
+        "show_inherited_class_members": show_inherited_class_members,
         "class_members_toctree": app.config.numpydoc_class_members_toctree,
         "attributes_as_param_list": app.config.numpydoc_attributes_as_param_list,
         "xref_param_type": app.config.numpydoc_xref_param_type,
@@ -270,7 +276,9 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_config_value("numpydoc_use_plots", None, False)
     app.add_config_value("numpydoc_use_blockquotes", None, False)
     app.add_config_value("numpydoc_show_class_members", True, True)
-    app.add_config_value("numpydoc_show_inherited_class_members", True, True)
+    app.add_config_value(
+        "numpydoc_show_inherited_class_members", True, True, types=(bool, dict)
+    )
     app.add_config_value("numpydoc_class_members_toctree", True, True)
     app.add_config_value("numpydoc_citation_re", "[a-z0-9_.-]+", True)
     app.add_config_value("numpydoc_attributes_as_param_list", True, True)

numpydoc/tests/test_numpydoc.py

@@ -1,5 +1,7 @@
 import pytest
+from collections import defaultdict
 from io import StringIO
+from pathlib import PosixPath
 from copy import deepcopy
 from numpydoc.numpydoc import mangle_docstrings, _clean_text_signature, update_config
 from numpydoc.xref import DEFAULT_LINKS
@@ -41,7 +43,7 @@ def __init__(self):
         self.warningiserror = False
 
 
-def test_mangle_docstrings():
+def test_mangle_docstrings_basic():
     s = """
 A top section before
 
@@ -69,6 +71,35 @@ def test_mangle_docstrings():
     assert "upper" not in [x.strip() for x in lines]
 
 
+def test_mangle_docstrings_inherited_class_members():
+    # if subclass docs are rendered, this PosixPath should have Path.samefile
+    p = """
+A top section before
+
+.. autoclass:: pathlib.PosixPath
+"""
+    lines = p.split("\n")
+    app = MockApp()
+    mangle_docstrings(app, "class", "pathlib.PosixPath", PosixPath, {}, lines)
+    lines = [x.strip() for x in lines]
+    assert "samefile" in lines
+    app.config.numpydoc_show_inherited_class_members = False
+    lines = p.split("\n")
+    mangle_docstrings(app, "class", "pathlib.PosixPath", PosixPath, {}, lines)
+    lines = [x.strip() for x in lines]
+    assert "samefile" not in lines
+    app.config.numpydoc_show_inherited_class_members = dict()
+    lines = p.split("\n")
+    mangle_docstrings(app, "class", "pathlib.PosixPath", PosixPath, {}, lines)
+    lines = [x.strip() for x in lines]
+    assert "samefile" in lines
+    app.config.numpydoc_show_inherited_class_members = defaultdict(lambda: False)
+    lines = p.split("\n")
+    mangle_docstrings(app, "class", "pathlib.PosixPath", PosixPath, {}, lines)
+    lines = [x.strip() for x in lines]
+    assert "samefile" not in lines
+
+
 def test_clean_text_signature():
     assert _clean_text_signature(None) is None
     assert _clean_text_signature("func($self)") == "func()"