diff options
author | Eric Larson <larson.eric.d@gmail.com> | 2022-07-13 08:55:05 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-07-13 08:55:05 -0400 |
commit | d9c8d6766a20500015f53ffc12fb6b552014912b (patch) | |
tree | 1e535781814ec9f40b7f3bb4d14ab8a1f1755dbe | |
parent | c796da669a9d3714126a3fde7221f9c47aef93c7 (diff) | |
download | numpydoc-d9c8d6766a20500015f53ffc12fb6b552014912b.tar.gz |
ENH: Add support for dict show_inherited_class_members (#415)
* ENH: Add support for dict show_inherited_class_members
* STY: Black
* TST: Add test
-rw-r--r-- | doc/install.rst | 12 | ||||
-rw-r--r-- | numpydoc/numpydoc.py | 12 | ||||
-rw-r--r-- | 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()" |