diff options
author | Matti Picus <matti.picus@gmail.com> | 2019-04-09 15:55:28 +0300 |
---|---|---|
committer | Eric Larson <larson.eric.d@gmail.com> | 2019-04-09 08:55:28 -0400 |
commit | a482f66913c1079d7439770f0119b55376bb1b81 (patch) | |
tree | 11077b3574e688917129b794481086f2460ffe53 | |
parent | d49deefa3dff875ff75dbe0ff58a16050321a14d (diff) | |
download | numpydoc-a482f66913c1079d7439770f0119b55376bb1b81.tar.gz |
ENH: accept autoclass member options (#205)
* ENH: accept autoclass member options
* BUG: options can be None (from review)
* MAINT: fixes from review
Co-Authored-By: mattip <matti.picus@gmail.com>
-rw-r--r-- | numpydoc/docscrape.py | 12 | ||||
-rw-r--r-- | numpydoc/numpydoc.py | 3 | ||||
-rw-r--r-- | numpydoc/tests/test_docscrape.py | 20 | ||||
-rw-r--r-- | numpydoc/tests/test_numpydoc.py | 56 |
4 files changed, 88 insertions, 3 deletions
diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index 4e3fc4c..b11332c 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -16,6 +16,7 @@ except ImportError: 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" @@ -597,18 +598,25 @@ class ClassDoc(NumpyDocString): 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 2544d0f..e25241d 100644 --- a/numpydoc/numpydoc.py +++ b/numpydoc/numpydoc.py @@ -154,6 +154,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 or {}) u_NL = sixu('\n') if what == 'module': # Strip top title @@ -199,7 +200,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 a0fb19c..fec53bc 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -866,11 +866,13 @@ This should be ignored and warned about 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.<locals>.BadSection' @@ -1337,6 +1339,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 0000000..3a0bd12 --- /dev/null +++ b/numpydoc/tests/test_numpydoc.py @@ -0,0 +1,56 @@ +# -*- 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 |