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

Author: pvanmulbregt

numpydoc/docscrape.py

@@ -229,6 +229,24 @@ 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)
+    # _funcs_rgx = re.compile(r"^\s*" + _funcname + r"(?P<morefuncs>([,\s]\s*" + _funcnamenext + r")*)" + 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)
@@ -245,48 +263,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):
@@ -432,25 +464,35 @@ 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 += ['']
+        if last_had_desc:
+            out += ['']
         out += ['']
+        # if 1:
+        #     print()
+        #     for l in out:
+        #         print(repr(l))
+        #     # print(out)
         return out
 
     def _str_index(self):

numpydoc/tests/test_docscrape.py

@@ -694,36 +694,51 @@ 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, str([len(doc6['See Also'])])
+    for funcs, desc in doc6['See Also']:
+        print(funcs, desc)
+        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 == 'func_j2':
+                assert desc == ['description of multiple'], str([desc, ['description of multiple']])
+
+        # s = str(doc6)
+        # print(repr(s))
+        # assert 1 == 0
 
 
 def test_see_also_parse_error():