ENH: Added support for multiple functions+description in a See Also block

numpydoc/docscrape.py

@@ -236,10 +236,30 @@ def _parse_param_list(self, content):
 
         return params
 
+    _role = r":(?P<role>\w+):"
+    _funcbacktick = r"`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_.-]+)`"
+    _funcplain = r"(?P<name2>[a-zA-Z0-9_.-]+)"
+    _funcname = r"(" + _role + _funcbacktick + r"|" + _funcplain + r")"
+    _funcnamenext = _funcname.replace('role', 'rolenext').replace('name', 'namenext')
+    _description = r"(?P<description>\s*:(\s+(?P<desc>\S+.*))?)?\s*$"
+    _func_rgx = re.compile(r"^\s*" + _funcname + r"\s*", re.X)
+    _line_rgx = re.compile(
+        r"^\s*"
+        + r"(?P<allfuncs>"          # group for all function names
+        + _funcname
+        + r"(?P<morefuncs>([,]\s+"
+        + _funcnamenext + r")*)"
+        + r")"                      # end of "allfuncs"
+        + r"(\s*,)?"                # Some function lists have a trailing comma
+        + _description,
+        re.X)
+
     _name_rgx = re.compile(r"^\s*(:(?P<role>\w+):"
                            r"`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_.-]+)`|"
                            r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
 
+    empty_description = '..'
+
     def _parse_see_also(self, content):
         """
         func_name : Descriptive text
@@ -252,48 +272,62 @@ def _parse_see_also(self, content):
 
         def parse_item_name(text):
             """Match ':role:`name`' or 'name'"""
-            m = self._name_rgx.match(text)
-            if m:
-                g = m.groups()
-                if g[1] is None:
-                    return g[3], None
-                else:
-                    return g[2], g[1]
-            raise ParseError("%s is not a item name" % text)
+            m = self._func_rgx.match(text)
+            if not m:
+                raise ParseError("%s is not a item name" % text)
+            role = m.groupdict().get('role')
+            if role:
+                name = m.group('name')
+            else:
+                name = m.group('name2')
+            return name, role, m
 
         def push_item(name, rest):
             if not name:
                 return
-            name, role = parse_item_name(name)
+            name, role, m2 = parse_item_name(name)
             items.append((name, list(rest), role))
             del rest[:]
 
-        current_func = None
         rest = []
 
         for line in content:
             if not line.strip():
                 continue
 
-            m = self._name_rgx.match(line)
-            if m and line[m.end():].strip().startswith(':'):
-                push_item(current_func, rest)
-                current_func, line = line[:m.end()], line[m.end():]
-                rest = [line.split(':', 1)[1].strip()]
-                if not rest[0]:
-                    rest = []
-            elif not line.startswith(' '):
-                push_item(current_func, rest)
-                current_func = None
-                if ',' in line:
-                    for func in line.split(','):
-                        if func.strip():
-                            push_item(func, [])
-                elif line.strip():
-                    current_func = line
-            elif current_func is not None:
+            ml = self._line_rgx.match(line)
+            description = None
+            if ml:
+                if 'description' in ml.groupdict():
+                    description = ml.groupdict().get('desc')
+            if not description and line.startswith(' '):
                 rest.append(line.strip())
-        push_item(current_func, rest)
+            elif ml:
+                funcs = []
+                text = ml.group('allfuncs')
+                while True:
+                    if not text.strip():
+                        break
+                    name, role, m2 = parse_item_name(text)
+                    # m2 = self._func_rgx.match(text)
+                    # if not m2:
+                    #     raise ParseError("%s is not a item name" % line)
+                    # role = m2.groupdict().get('role')
+                    # if role:
+                    #     name = m2.group('name')
+                    # else:
+                    #     name = m2.group('name2')
+                    funcs.append((name, role))
+                    text = text[m2.end():].strip()
+                    if text and text[0] == ',':
+                        text = text[1:].strip()
+                if description:
+                    rest = [description]
+                else:
+                    rest = []
+                items.append((funcs, rest))
+            else:
+                raise ParseError("%s is not a item name" % line)
         return items
 
     def _parse_index(self, section, content):
@@ -440,24 +474,30 @@ def _str_see_also(self, func_role):
             return []
         out = []
         out += self._str_header("See Also")
+        out += ['']
         last_had_desc = True
-        for func, desc, role in self['See Also']:
-            if role:
-                link = ':%s:`%s`' % (role, func)
-            elif func_role:
-                link = ':%s:`%s`' % (func_role, func)
-            else:
-                link = "`%s`_" % func
-            if desc or last_had_desc:
-                out += ['']
-                out += [link]
-            else:
-                out[-1] += ", %s" % link
+        for funcs, desc in self['See Also']:
+            assert isinstance(funcs, (list, tuple))
+            links = []
+            for func, role in funcs:
+                if role:
+                    link = ':%s:`%s`' % (role, func)
+                elif func_role:
+                    link = ':%s:`%s`' % (func_role, func)
+                else:
+                    link = "`%s`_" % func
+                links.append(link)
+            link = ', '.join(links)
+            out += [link]
             if desc:
                 out += self._str_indent([' '.join(desc)])
                 last_had_desc = True
             else:
                 last_had_desc = False
+                out += self._str_indent([self.empty_description])
+
+        if last_had_desc:
+            out += ['']
         out += ['']
         return out
 

numpydoc/tests/test_docscrape.py

@@ -331,13 +331,15 @@ def _strip_blank_lines(s):
 
 
 def line_by_line_compare(a, b):
+    empty_description = '..'
+    rgx = re.compile(r"^\s+" + re.escape(empty_description) + "$")
+
     a = textwrap.dedent(a)
     b = textwrap.dedent(b)
-    a = [l.rstrip() for l in _strip_blank_lines(a).split('\n')]
-    b = [l.rstrip() for l in _strip_blank_lines(b).split('\n')]
+    a = [rgx.sub('', l.rstrip()) for l in _strip_blank_lines(a).split('\n')]
+    b = [rgx.sub('', l.rstrip()) for l in _strip_blank_lines(b).split('\n')]
     assert all(x == y for x, y in zip(a, b))
 
-
 def test_str():
     # doc_txt has the order of Notes and See Also sections flipped.
     # This should be handled automatically, and so, one thing this test does
@@ -709,36 +711,46 @@ def test_see_also():
              multiple lines
     func_f, func_g, :meth:`func_h`, func_j,
     func_k
+    func_f1, func_g1, :meth:`func_h1`, func_j1
+    func_f2, func_g2, :meth:`func_h2`, func_j2 : description of multiple
     :obj:`baz.obj_q`
     :obj:`~baz.obj_r`
     :class:`class_j`: fubar
         foobar
     """)
 
-    assert len(doc6['See Also']) == 13
-    for func, desc, role in doc6['See Also']:
-        if func in ('func_a', 'func_b', 'func_c', 'func_f',
-                    'func_g', 'func_h', 'func_j', 'func_k', 'baz.obj_q',
-                    '~baz.obj_r'):
-            assert(not desc)
-        else:
-            assert(desc)
-
-        if func == 'func_h':
-            assert role == 'meth'
-        elif func == 'baz.obj_q' or func == '~baz.obj_r':
-            assert role == 'obj'
-        elif func == 'class_j':
-            assert role == 'class'
-        else:
-            assert role is None
-
-        if func == 'func_d':
-            assert desc == ['some equivalent func']
-        elif func == 'foo.func_e':
-            assert desc == ['some other func over', 'multiple lines']
-        elif func == 'class_j':
-            assert desc == ['fubar', 'foobar']
+    assert len(doc6['See Also']) == 10
+    for funcs, desc in doc6['See Also']:
+        for func, role in funcs:
+            if func in ('func_a', 'func_b', 'func_c', 'func_f',
+                        'func_g', 'func_h', 'func_j', 'func_k', 'baz.obj_q',
+                        'func_f1', 'func_g1', 'func_h1', 'func_j1',
+                        '~baz.obj_r'):
+                assert (not desc), str([func, desc])
+            elif func in ('func_f2', 'func_g2', 'func_h2', 'func_j2'):
+                    assert (desc), str([func, desc])
+            else:
+                assert(desc), str([func, desc])
+
+            if func == 'func_h':
+                assert role == 'meth'
+            elif func == 'baz.obj_q' or func == '~baz.obj_r':
+                assert role == 'obj'
+            elif func == 'class_j':
+                assert role == 'class'
+            elif func in ['func_h1', 'func_h2']:
+                assert role == 'meth'
+            else:
+                assert role is None, str([func, role])
+
+            if func == 'func_d':
+                assert desc == ['some equivalent func']
+            elif func == 'foo.func_e':
+                assert desc == ['some other func over', 'multiple lines']
+            elif func == 'class_j':
+                assert desc == ['fubar', 'foobar']
+            elif func in ['func_f2', 'func_g2', 'func_h2', 'func_j2']:
+                assert desc == ['description of multiple'], str([desc, ['description of multiple']])
 
 
 def test_see_also_parse_error():