Merge pull request #106 from jnothman/member-definition-list

Format attributes like parameters

Author: stefanv

numpydoc/docscrape_sphinx.py

@@ -79,21 +79,136 @@ def _str_returns(self, name='Returns'):
                 out += ['']
         return out
 
-    def _str_param_list(self, name):
+    def _process_param(self, param, desc, autosum):
+        """Determine how to display a parameter
+
+        Emulates autosummary behavior if autosum is not None.
+
+        Parameters
+        ----------
+        param : str
+            The name of the parameter
+        desc : list of str
+            The parameter description as given in the docstring. This is
+            ignored when autosummary logic applies.
+        autosum : list or None
+            If a list, autosummary-style behaviour will apply for params
+            that are attributes of the class and have a docstring.
+            Names for autosummary generation will be appended to this list.
+
+            If None, autosummary is disabled.
+
+        Returns
+        -------
+        display_param : str
+            The marked up parameter name for display. This may include a link
+            to the corresponding attribute's own documentation.
+        desc : list of str
+            A list of description lines. This may be identical to the input
+            ``desc``, if ``autosum is None`` or ``param`` is not a class
+            attribute, or it will be a summary of the class attribute's
+            docstring.
+
+        Notes
+        -----
+        This does not have the autosummary functionality to display a method's
+        signature, and hence is not used to format methods.  It may be
+        complicated to incorporate autosummary's signature mangling, as it
+        relies on Sphinx's plugin mechanism.
+        """
+        param = param.strip()
+        display_param = '**%s**' % param
+
+        if autosum is None:
+            return display_param, desc
+
+        param_obj = getattr(self._obj, param, None)
+        if not (callable(param_obj)
+                or isinstance(param_obj, property)
+                or inspect.isgetsetdescriptor(param_obj)):
+            param_obj = None
+        obj_doc = pydoc.getdoc(param_obj)
+
+        if not (param_obj and obj_doc):
+            return display_param, desc
+
+        prefix = getattr(self, '_name', '')
+        if prefix:
+            autosum_prefix = '~%s.' % prefix
+            link_prefix = '%s.' % prefix
+        else:
+            autosum_prefix = ''
+            link_prefix = ''
+
+        # Referenced object has a docstring
+        autosum.append("    %s%s" % (autosum_prefix, param))
+        display_param = ':obj:`%s <%s%s>`' % (param,
+                                              link_prefix,
+                                              param)
+        if obj_doc:
+            # Overwrite desc. Take summary logic of autosummary
+            desc = re.split('\n\s*\n', obj_doc.strip(), 1)[0]
+            # XXX: Should this have DOTALL?
+            #      It does not in autosummary
+            m = re.search(r"^([A-Z].*?\.)(?:\s|$)",
+                          ' '.join(desc.split()))
+            if m:
+                desc = m.group(1).strip()
+            else:
+                desc = desc.partition('\n')[0]
+            desc = desc.split('\n')
+        return display_param, desc
+
+    def _str_param_list(self, name, fake_autosummary=False):
+        """Generate RST for a listing of parameters or similar
+
+        Parameter names are displayed as bold text, and descriptions
+        are in blockquotes.  Descriptions may therefore contain block
+        markup as well.
+
+        Parameters
+        ----------
+        name : str
+            Section name (e.g. Parameters)
+        fake_autosummary : bool
+            When True, the parameter names may correspond to attributes of the
+            object beign documented, usually ``property`` instances on a class.
+            In this case, names will be linked to fuller descriptions.
+
+        Returns
+        -------
+        rst : list of str
+        """
         out = []
         if self[name]:
+            if fake_autosummary:
+                autosum = []
+            else:
+                autosum = None
+
             out += self._str_field_list(name)
             out += ['']
             for param, param_type, desc in self[name]:
+                display_param, desc = self._process_param(param, desc, autosum)
+
                 if param_type:
-                    out += self._str_indent(['**%s** : %s' % (param.strip(),
-                                                              param_type)])
+                    out += self._str_indent(['%s : %s' % (display_param,
+                                                          param_type)])
                 else:
-                    out += self._str_indent(['**%s**' % param.strip()])
+                    out += self._str_indent([display_param])
                 if desc:
-                    out += ['']
+                    out += ['']  # produces a blockquote, rather than a dt/dd
                     out += self._str_indent(desc, 8)
                 out += ['']
+
+            if fake_autosummary and autosum:
+                if self.class_members_toctree:
+                    autosum.insert(0, '    :toctree:')
+                autosum.insert(0, '.. autosummary::')
+                out += ['..', '    HACK to make autogen generate docs:']
+                out += self._str_indent(autosum, 4)
+                out += ['']
+
         return out
 
     @property
@@ -130,7 +245,7 @@ def _str_member_list(self, name):
                         or inspect.isgetsetdescriptor(param_obj)):
                     param_obj = None
 
-                if param_obj and (pydoc.getdoc(param_obj) or not desc):
+                if param_obj and pydoc.getdoc(param_obj):
                     # Referenced object has a docstring
                     autosum += ["   %s%s" % (prefix, param)]
                 else:
@@ -250,7 +365,8 @@ def __str__(self, indent=0, func_role="obj"):
             'notes': self._str_section('Notes'),
             'references': self._str_references(),
             'examples': self._str_examples(),
-            'attributes': self._str_member_list('Attributes'),
+            'attributes': self._str_param_list('Attributes',
+                                               fake_autosummary=True),
             'methods': self._str_member_list('Methods'),
         }
         ns = dict((k, '\n'.join(v)) for k, v in ns.items())

numpydoc/tests/test_docscrape.py

@@ -17,6 +17,8 @@
 from nose.tools import (assert_equal, assert_raises, assert_list_equal,
                         assert_true)
 
+assert_list_equal.__self__.maxDiff = None
+
 if sys.version_info[0] >= 3:
     sixu = lambda s: s
 else:
@@ -897,8 +899,17 @@ def test_duplicate_signature():
         Current time.
     y : ndarray
         Current variable values.
-    x : float
-        Some parameter
+
+        * hello
+        * world
+    an_attribute : float
+        The docstring is printed instead
+    no_docstring : str
+        But a description
+    no_docstring2 : str
+    multiline_sentence
+    midword_period
+    no_period
 
     Methods
     -------
@@ -934,8 +945,17 @@ def test_class_members_doc():
         Current time.
     y : ndarray
         Current variable values.
-    x : float
-        Some parameter
+
+        * hello
+        * world
+    an_attribute : float
+        The docstring is printed instead
+    no_docstring : str
+        But a description
+    no_docstring2 : str
+    multiline_sentence
+    midword_period
+    no_period
 
     Methods
     -------
@@ -952,10 +972,38 @@ def test_class_members_doc():
 def test_class_members_doc_sphinx():
     class Foo:
         @property
-        def x(self):
+        def an_attribute(self):
             """Test attribute"""
             return None
 
+        @property
+        def no_docstring(self):
+            return None
+
+        @property
+        def no_docstring2(self):
+            return None
+
+        @property
+        def multiline_sentence(self):
+            """This is a
+            sentence. It spans multiple lines."""
+            return None
+
+        @property
+        def midword_period(self):
+            """The sentence for numpy.org."""
+            return None
+
+        @property
+        def no_period(self):
+            """This does not have a period
+            so we truncate its summary to the first linebreak
+
+            Apparently.
+            """
+            return None
+
     doc = SphinxClassDoc(Foo, class_doc_txt)
     non_blank_line_by_line_compare(str(doc),
     """
@@ -975,17 +1023,36 @@ def x(self):
 
     For usage examples, see `ode`.
 
-    .. rubric:: Attributes
-
-    .. autosummary::
-       :toctree:
-
-       x
-
-    =====  ==========
-    **t**  (float) Current time.
-    **y**  (ndarray) Current variable values.
-    =====  ==========
+    :Attributes:
+
+        **t** : float
+            Current time.
+        **y** : ndarray
+            Current variable values.
+
+            * hello
+            * world
+        :obj:`an_attribute <an_attribute>` : float
+            Test attribute
+        **no_docstring** : str
+            But a description
+        **no_docstring2** : str
+        :obj:`multiline_sentence <multiline_sentence>`
+            This is a sentence.
+        :obj:`midword_period <midword_period>`
+            The sentence for numpy.org.
+        :obj:`no_period <no_period>`
+            This does not have a period
+
+    ..
+        HACK to make autogen generate docs:
+        .. autosummary::
+            :toctree:
+
+            an_attribute
+            multiline_sentence
+            midword_period
+            no_period
 
     .. rubric:: Methods