Handle numpy-style *args parameters

Author: krassowski

docstring_to_markdown/rst.py

@@ -164,7 +164,7 @@ def _start_block(self, language: str):
 
     def consume(self, line: str):
         if not self._block_started:
-            raise ValueError('Block has not started')
+            raise ValueError('Block has not started')   # pragma: no cover
         self._buffer.append(line)
 
     def finish_consumption(self, final: bool) -> str:
@@ -399,13 +399,22 @@ def flush_buffer():
             # ok, we are not in any code block (it may start with the next line, but this line is clear - or empty)
 
             # lists handling: items detection
-            match = re.match(r'^(?P<argument>[^: ]+) : (?P<type>.+)$', trimmed_line)
+            # this one does NOT allow spaces on the left hand side (to avoid false positive matches)
+            match = re.match(r'^(?P<argument>[^:\s]+) : (?P<type>.+)$', trimmed_line)
             if match:
                 line = '- `' + match.group('argument') + '`: ' + match.group('type') + ''
             elif most_recent_section == 'Parameters':
                 kwargs_or_args_match = re.match(r'^(?P<other_args>\*\*kwargs|\*args)$', trimmed_line)
                 if kwargs_or_args_match:
                     line = '- `' + kwargs_or_args_match.group('other_args') + '`'
+                else:
+                    numpy_args_match = re.match(
+                        r'^(?P<arg1>[^:\s]+\d), (?P<arg2>[^:\s]+\d), \.\.\. : (?P<type>.+)$',
+                        trimmed_line
+                    )
+                    if numpy_args_match:
+                        groups = numpy_args_match.groupdict()
+                        line = f'- `{groups["arg1"]}`, `{groups["arg2"]}`, `...`: {groups["type"]}'
             else:
                 if trimmed_line.rstrip() in RST_SECTIONS:
                     most_recent_section = trimmed_line.rstrip()

tests/test_rst.py

@@ -293,6 +293,22 @@ def func(): pass
     For other keyword-only arguments, see the ufunc docs.
 """
 
+NUMPY_ARGS_PARAMETERS = """
+Parameters
+----------
+arys1, arys2, ... : array_like
+    One or more input arrays.
+"""
+
+
+NUMPY_ARGS_PARAMETERS_MARKDOWN = """
+#### Parameters
+
+- `arys1`, `arys2`, `...`: array_like
+    One or more input arrays.
+"""
+
+
 INITIAL_SIGNATURE = """\
 absolute1(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj])
 
@@ -467,6 +483,10 @@ def func(): pass
         'rst': KWARGS_PARAMETERS,
         'md': KWARGS_PARAMETERS_MARKDOWN
     },
+    'converts numpy-style *args parameters': {
+        'rst': NUMPY_ARGS_PARAMETERS,
+        'md': NUMPY_ARGS_PARAMETERS_MARKDOWN
+    },
     'converts signature in the first line': {
         'rst': INITIAL_SIGNATURE,
         'md': INITIAL_SIGNATURE_MARKDOWN