From 60b3fa31a5ce79b0f866a85c529e34b2936b7ac6 Mon Sep 17 00:00:00 2001 From: mattip Date: Mon, 8 Apr 2019 02:00:38 +0300 Subject: [PATCH 1/3] ENH: accept autoclass member options --- numpydoc/docscrape.py | 12 +++++-- numpydoc/numpydoc.py | 3 +- numpydoc/tests/test_docscrape.py | 20 ++++++++++++ numpydoc/tests/test_numpydoc.py | 55 ++++++++++++++++++++++++++++++++ 4 files changed, 87 insertions(+), 3 deletions(-) create mode 100644 numpydoc/tests/test_numpydoc.py diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index f3453c65..b3f0bb78 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -16,6 +16,7 @@ import copy import sys +from sphinx.ext.autodoc import ALL def strip_blank_lines(l): "Remove leading and trailing blank lines from a list of lines" @@ -593,18 +594,25 @@ def __init__(self, cls, doc=None, modulename='', func_doc=FunctionDoc, NumpyDocString.__init__(self, doc) - if config.get('show_class_members', True): + _members = config.get('members', []) + if _members is ALL: + _members = None + _exclude = config.get('exclude-members', []) + + if config.get('show_class_members', True) and _exclude is not ALL: def splitlines_x(s): if not s: return [] else: return s.splitlines() - for field, items in [('Methods', self.methods), ('Attributes', self.properties)]: if not self[field]: doc_list = [] for name in sorted(items): + if (name in _exclude or + (_members and name not in _members)): + continue try: doc_item = pydoc.getdoc(getattr(self._cls, name)) doc_list.append( diff --git a/numpydoc/numpydoc.py b/numpydoc/numpydoc.py index c8e676f5..9eb50ba1 100644 --- a/numpydoc/numpydoc.py +++ b/numpydoc/numpydoc.py @@ -132,6 +132,7 @@ def mangle_docstrings(app, what, name, obj, options, lines): app.config.numpydoc_show_inherited_class_members, 'class_members_toctree': app.config.numpydoc_class_members_toctree} + cfg.update(options) u_NL = sixu('\n') if what == 'module': # Strip top title @@ -177,7 +178,7 @@ def mangle_signature(app, what, name, obj, options, sig, retann): if not hasattr(obj, '__doc__'): return - doc = get_doc_object(obj) + doc = get_doc_object(obj, config={'show_class_members': False}) sig = doc['Signature'] or getattr(obj, '__text_signature__', None) if sig: sig = re.sub(sixu("^[^(]*"), sixu(""), sig) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 20859488..01d281f5 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -796,11 +796,13 @@ class BadSection(object): pass with warnings.catch_warnings(record=True) as w: + warnings.filterwarnings('always', '', UserWarning) NumpyDocString(doc_text) assert len(w) == 1 assert "Unknown section Mope" == str(w[0].message) with warnings.catch_warnings(record=True) as w: + warnings.filterwarnings('always', '', UserWarning) SphinxClassDoc(BadSection) assert len(w) == 1 assert('test_docscrape.test_unknown_section..BadSection' @@ -1267,6 +1269,24 @@ def test_args_and_kwargs(): Keyword arguments """) +def test_autoclass(): + cfg=dict(show_class_members=True, + show_inherited_class_members=True) + doc = SphinxClassDoc(str, ''' +A top section before + +.. autoclass:: str + ''', config=cfg) + line_by_line_compare(str(doc), r''' +A top section before + +.. autoclass:: str + +.. rubric:: Methods + + + ''') + if __name__ == "__main__": import pytest diff --git a/numpydoc/tests/test_numpydoc.py b/numpydoc/tests/test_numpydoc.py new file mode 100644 index 00000000..8a55a8c8 --- /dev/null +++ b/numpydoc/tests/test_numpydoc.py @@ -0,0 +1,55 @@ +# -*- encoding:utf-8 -*- +from __future__ import division, absolute_import, print_function + +from numpydoc.numpydoc import mangle_docstrings +from sphinx.ext.autodoc import ALL + +class MockConfig(): + numpydoc_use_plots = False + numpydoc_use_blockquotes = True + numpydoc_show_class_members = True + numpydoc_show_inherited_class_members = True + numpydoc_class_members_toctree = True + templates_path = [] + numpydoc_edit_link = False + numpydoc_citation_re = '[a-z0-9_.-]+' + +class MockBuilder(): + config = MockConfig() + +class MockApp(): + config = MockConfig() + builder = MockBuilder() + translator = None + + +app = MockApp() +app.builder.app = app + +def test_mangle_docstrings(): + s =''' +A top section before + +.. autoclass:: str + ''' + lines = s.split('\n') + doc = mangle_docstrings(MockApp(), 'class', 'str', str, {}, lines) + assert 'rpartition' in [x.strip() for x in lines] + + lines = s.split('\n') + doc = mangle_docstrings(MockApp(), 'class', 'str', str, {'members':['upper']}, lines) + assert 'rpartition' not in [x.strip() for x in lines] + assert 'upper' in [x.strip() for x in lines] + + lines = s.split('\n') + doc = mangle_docstrings(MockApp(), 'class', 'str', str, {'exclude-members': ALL}, lines) + assert 'rpartition' not in [x.strip() for x in lines] + assert 'upper' not in [x.strip() for x in lines] + + lines = s.split('\n') + doc = mangle_docstrings(MockApp(), 'class', 'str', str, {'exclude-members': 'upper'}, lines) + assert 'rpartition' in [x.strip() for x in lines] + assert 'upper' not in [x.strip() for x in lines] + +if __name__ == "__main__": + import pytest From a9da83d4f1f520bdb6c0961036ee377b7354b18b Mon Sep 17 00:00:00 2001 From: mattip Date: Mon, 8 Apr 2019 17:39:13 +0300 Subject: [PATCH 2/3] BUG: options can be None (from review) --- numpydoc/numpydoc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/numpydoc/numpydoc.py b/numpydoc/numpydoc.py index 9eb50ba1..110fc6bc 100644 --- a/numpydoc/numpydoc.py +++ b/numpydoc/numpydoc.py @@ -132,7 +132,7 @@ def mangle_docstrings(app, what, name, obj, options, lines): app.config.numpydoc_show_inherited_class_members, 'class_members_toctree': app.config.numpydoc_class_members_toctree} - cfg.update(options) + cfg.update(options or {}) u_NL = sixu('\n') if what == 'module': # Strip top title From 75a6dede998348ce06e8af589c4dce1c64e60b3e Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Tue, 9 Apr 2019 13:58:56 +0300 Subject: [PATCH 3/3] MAINT: fixes from review Co-Authored-By: mattip --- numpydoc/tests/test_numpydoc.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/numpydoc/tests/test_numpydoc.py b/numpydoc/tests/test_numpydoc.py index 8a55a8c8..3a0bd123 100644 --- a/numpydoc/tests/test_numpydoc.py +++ b/numpydoc/tests/test_numpydoc.py @@ -37,7 +37,7 @@ def test_mangle_docstrings(): assert 'rpartition' in [x.strip() for x in lines] lines = s.split('\n') - doc = mangle_docstrings(MockApp(), 'class', 'str', str, {'members':['upper']}, lines) + doc = mangle_docstrings(MockApp(), 'class', 'str', str, {'members': ['upper']}, lines) assert 'rpartition' not in [x.strip() for x in lines] assert 'upper' in [x.strip() for x in lines] @@ -47,7 +47,8 @@ def test_mangle_docstrings(): assert 'upper' not in [x.strip() for x in lines] lines = s.split('\n') - doc = mangle_docstrings(MockApp(), 'class', 'str', str, {'exclude-members': 'upper'}, lines) + doc = mangle_docstrings(MockApp(), 'class', 'str', str, + {'exclude-members': ['upper']}, lines) assert 'rpartition' in [x.strip() for x in lines] assert 'upper' not in [x.strip() for x in lines]