Merge pull request #161 from jorisvandenbossche/attributes_as_param_list

Add option to use member listing for attributes

Author: rgommers

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
 

numpydoc/docscrape_sphinx.py

@@ -36,6 +36,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')]
@@ -384,8 +385,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())

numpydoc/numpydoc.py

@@ -152,7 +152,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}
 
     cfg.update(options or {})
     u_NL = sixu('\n')
@@ -227,6 +229,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)

numpydoc/tests/test_docscrape.py

@@ -1295,6 +1295,43 @@ def no_period(self):
     """)
 
 
+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"""
+            return None
+
+    attr_doc = """:Attributes:
+
+    :obj:`an_attribute <an_attribute>`
+        Test attribute"""
+
+    assert attr_doc in str(SphinxClassDoc(Foo))
+    assert "Another description" not 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))
+    assert "Another description" not in str(SphinxClassDoc(Foo, config=cfg))
+
+
 def test_templated_sections():
     doc = SphinxClassDoc(None, class_doc_txt,
                          config={'template': jinja2.Template('{{examples}}\n{{parameters}}')})

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()