From d9c8d6766a20500015f53ffc12fb6b552014912b Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Wed, 13 Jul 2022 08:55:05 -0400 Subject: ENH: Add support for dict show_inherited_class_members (#415) * ENH: Add support for dict show_inherited_class_members * STY: Black * TST: Add test --- doc/install.rst | 12 ++++++++++-- numpydoc/numpydoc.py | 12 ++++++++++-- numpydoc/tests/test_numpydoc.py | 33 ++++++++++++++++++++++++++++++++- 3 files changed, 52 insertions(+), 5 deletions(-) diff --git a/doc/install.rst b/doc/install.rst index fb3c26b..28b75a0 100644 --- a/doc/install.rst +++ b/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 diff --git a/numpydoc/numpydoc.py b/numpydoc/numpydoc.py index e656fb5..57016f9 100644 --- a/numpydoc/numpydoc.py +++ b/numpydoc/numpydoc.py @@ -162,12 +162,18 @@ DEDUPLICATION_TAG = " !! processed by numpydoc !!" 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) diff --git a/numpydoc/tests/test_numpydoc.py b/numpydoc/tests/test_numpydoc.py index 0c8b6d6..d414b1c 100644 --- a/numpydoc/tests/test_numpydoc.py +++ b/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 @@ class MockApp: self.warningiserror = False -def test_mangle_docstrings(): +def test_mangle_docstrings_basic(): s = """ A top section before @@ -69,6 +71,35 @@ A top section before 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()" -- cgit v1.2.1