From 5c2f4fee21108bbca3c44ceae340e2f8bdd64ec5 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 30 Mar 2018 09:39:08 +0200 Subject: [PATCH 1/5] Add option to use member listing for attributes --- numpydoc/docscrape_sphinx.py | 7 +++++-- numpydoc/numpydoc.py | 5 ++++- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index 087ddafb..1da99ed4 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -33,6 +33,7 @@ def load_config(self, config): self.use_plots = config.get('use_plots', False) self.use_blockquotes = config.get('use_blockquotes', False) self.class_members_toctree = config.get('class_members_toctree', True) + self.attributes_as_param_list = config.get('attributes_as_param_list', True) self.template = config.get('template', None) if self.template is None: template_dirs = [os.path.join(os.path.dirname(__file__), 'templates')] @@ -366,8 +367,10 @@ def __str__(self, indent=0, func_role="obj"): 'notes': self._str_section('Notes'), 'references': self._str_references(), 'examples': self._str_examples(), - 'attributes': self._str_param_list('Attributes', - fake_autosummary=True), + 'attributes': + self._str_param_list('Attributes', fake_autosummary=True) + if self.attributes_as_param_list + else self._str_member_list('Attributes'), 'methods': self._str_member_list('Methods'), } ns = dict((k, '\n'.join(v)) for k, v in ns.items()) diff --git a/numpydoc/numpydoc.py b/numpydoc/numpydoc.py index 2b259af3..e4327fa6 100644 --- a/numpydoc/numpydoc.py +++ b/numpydoc/numpydoc.py @@ -115,7 +115,9 @@ def mangle_docstrings(app, what, name, obj, options, lines): 'show_class_members': app.config.numpydoc_show_class_members, 'show_inherited_class_members': app.config.numpydoc_show_inherited_class_members, - 'class_members_toctree': app.config.numpydoc_class_members_toctree} + 'class_members_toctree': app.config.numpydoc_class_members_toctree, + 'attributes_as_param_list': + app.config.numpydoc_attributes_as_param_list} u_NL = sixu('\n') if what == 'module': @@ -186,6 +188,7 @@ def setup(app, get_doc_object_=get_doc_object): app.add_config_value('numpydoc_show_inherited_class_members', True, True) 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) # Extra mangling domains app.add_domain(NumpyPythonDomain) From b311805f5074084e2783c9e6c0dd8f4e57fb87fd Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 30 Mar 2018 09:52:58 +0200 Subject: [PATCH 2/5] add test --- numpydoc/tests/test_docscrape.py | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 2fb4eb5a..7c9ca99c 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -1179,6 +1179,32 @@ def no_period(self): """) +def test_class_members_as_member_list(): + + class Foo: + @property + def an_attribute(self): + """Test attribute""" + return None + + attr_doc = """:Attributes: + + :obj:`an_attribute ` + Test attribute""" + + assert attr_doc in str(SphinxClassDoc(Foo)) + + attr_doc2 = """.. rubric:: Attributes + +.. autosummary:: + :toctree: + + an_attribute""" + + cfg = dict(attributes_as_param_list=False) + assert attr_doc2 in str(SphinxClassDoc(Foo, config=cfg)) + + def test_templated_sections(): doc = SphinxClassDoc(None, class_doc_txt, config={'template': jinja2.Template('{{examples}}\n{{parameters}}')}) From 58cf671104cc35d0b6c8340d15a40632bd322240 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 12 Apr 2019 08:21:47 +0200 Subject: [PATCH 3/5] fix test after update --- numpydoc/tests/test_numpydoc.py | 1 + 1 file changed, 1 insertion(+) diff --git a/numpydoc/tests/test_numpydoc.py b/numpydoc/tests/test_numpydoc.py index 3a0bd123..0fd3c37a 100644 --- a/numpydoc/tests/test_numpydoc.py +++ b/numpydoc/tests/test_numpydoc.py @@ -13,6 +13,7 @@ class MockConfig(): templates_path = [] numpydoc_edit_link = False numpydoc_citation_re = '[a-z0-9_.-]+' + numpydoc_attributes_as_param_list = True class MockBuilder(): config = MockConfig() From a4c1ca1df10ed55444f0fa56ff8a2aa8153fedb8 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 12 Apr 2019 08:32:24 +0200 Subject: [PATCH 4/5] add test that description of class docstring is not used for attributes --- numpydoc/tests/test_docscrape.py | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index dd1a8a22..dc288592 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -1279,9 +1279,18 @@ def no_period(self): """) -def test_class_members_as_member_list(): +def test_class_attributes_as_member_list(): class Foo: + """ + Class docstring. + + Attributes + ---------- + an_attribute + Another description that is not used. + + """ @property def an_attribute(self): """Test attribute""" @@ -1293,6 +1302,7 @@ def an_attribute(self): Test attribute""" assert attr_doc in str(SphinxClassDoc(Foo)) + assert "Another description" not in str(SphinxClassDoc(Foo)) attr_doc2 = """.. rubric:: Attributes @@ -1303,6 +1313,7 @@ def an_attribute(self): cfg = dict(attributes_as_param_list=False) assert attr_doc2 in str(SphinxClassDoc(Foo, config=cfg)) + assert "Another description" not in str(SphinxClassDoc(Foo, config=cfg)) def test_templated_sections(): From d4d34454b22ce2565ab80112f62b7edbd037bc25 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 12 Apr 2019 08:40:40 +0200 Subject: [PATCH 5/5] add to docs --- doc/install.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/install.rst b/doc/install.rst index 260b4ee1..1fa0fde5 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -42,6 +42,11 @@ numpydoc_use_blockquotes : bool Until version 0.8, parameter definitions were shown as blockquotes, rather than in a definition list. If your styling requires blockquotes, switch this config option to True. This option will be removed in version 0.10. +numpydoc_attributes_as_param_list : bool + Whether to format the Attributes section of a class page in the same way + as the Parameter section. If it's False, the Attributes section will be + formatted as the Methods section using an autosummary table. + ``True`` by default. numpydoc_edit_link : bool .. deprecated:: edit your HTML template instead