use numpydoc to capture function signature for var_positional args

murrayrm · murrayrm · commit 884e86516c86 · 2025-02-02T20:28:21.000-08:00
diff --git a/control/bdalg.py b/control/bdalg.py
@@ -69,8 +69,8 @@
            'combine_tf', 'split_tf']
 
 
-def series(sys1, *sysn, **kwargs):
-    r"""series(sys1, sys2, [..., sysn])
+def series(*sys, **kwargs):
+    r"""series(sys1, sys2[, ..., sysn])
 
     Return series connection (`sysn` \* ...\  \*) `sys2` \* `sys1`.
 
@@ -136,13 +136,13 @@ def series(sys1, *sysn, **kwargs):
     (2, 1, 5)
 
     """
-    sys = reduce(lambda x, y: y * x, sysn, sys1)
+    sys = reduce(lambda x, y: y * x, sys[1:], sys[0])
     sys.update_names(**kwargs)
     return sys
 
 
-def parallel(sys1, *sysn, **kwargs):
-    r"""parallel(sys1, sys2, [..., sysn])
+def parallel(*sys, **kwargs):
+    r"""parallel(sys1, sys2[, ..., sysn])
 
     Return parallel connection `sys1` + `sys2` (+ ...\  + `sysn`).
 
@@ -206,7 +206,7 @@ def parallel(sys1, *sysn, **kwargs):
     (3, 4, 7)
 
     """
-    sys = reduce(lambda x, y: x + y, sysn, sys1)
+    sys = reduce(lambda x, y: x + y, sys[1:], sys[0])
     sys.update_names(**kwargs)
     return sys
 
@@ -354,7 +354,7 @@ def feedback(sys1, sys2=1, sign=-1, **kwargs):
     return sys
 
 def append(*sys, **kwargs):
-    """append(sys1, sys2, [..., sysn])
+    """append(sys1, sys2[, ..., sysn])
 
     Group LTI models by appending their inputs and outputs.
 
diff --git a/control/freqplot.py b/control/freqplot.py
@@ -2172,7 +2172,9 @@ def gangof4_response(
 def gangof4_plot(
         *args, omega=None, omega_limits=None, omega_num=None,
         Hz=False, **kwargs):
-    """Plot response of "Gang of 4" transfer functions.
+    """gangof4_plot(response) | gangof4_plot(P, C, omega)
+
+    Plot response of "Gang of 4" transfer functions.
 
     Plots a 2x2 frequency response for the "Gang of 4" sensitivity
     functions [T, PS; CS, S].  Can be called in one of two ways:
diff --git a/control/margins.py b/control/margins.py
@@ -507,11 +507,13 @@ def phase_crossover_frequencies(sys):
 
 
 def margin(*args):
-    """margin(sysdata)
+    """
+    margin(sys) \
+    margin(mag, phase, omega)
 
     Gain and phase margins and associated crossover frequencies.
 
-    Can be called as ``margin(sys)`` where ``sys`` is a SISO LTI sytem or
+    Can be called as ``margin(sys)`` where ``sys`` is a SISO LTI system or
     ``margin(mag, phase, omega)``.
 
     Parameters
diff --git a/control/stochsys.py b/control/stochsys.py
@@ -213,8 +213,8 @@ def dlqe(*args, **kwargs):
 
     Parameters
     ----------
-    A, G : 2D array_like
-        Dynamics and noise input matrices.
+    A, G, C : 2D array_like
+        Dynamics, process noise (disturbance), and output matrices.
     QN, RN : 2D array_like
         Process and sensor noise covariance matrices.
     NN : 2D array, optional
diff --git a/control/tests/docstrings_test.py b/control/tests/docstrings_test.py
@@ -36,23 +36,6 @@
     control.tf,                                 # tested separately below
 ]
 
-# Checksums to use for checking whether a docstring has changed
-function_docstring_hash = {
-    control.append:                     'fad0bd0766754c3524e0ea27b06bf74a',
-    control.describing_function_plot:   '95f894706b1d3eeb3b854934596af09f',
-    control.dlqe:                       'e1e9479310e4e5a6f50f5459fb3d2dfb',
-    control.dlqr:                       '56d7f3a452bc8d7a7256a52d9d1dcb37',
-    control.lqe:                        '0447235d11b685b9dfaf485dd01fdb9a',
-    control.lqr:                        'a3e0a85f781fc9c0f69a4b7da4f0bd22',
-    control.margin:                     'f02b3034f5f1d44ce26f916cc3e51600',
-    control.parallel:                   'bfc470aef75dbb923f9c6fb8bf3c9b43',
-    control.series:                     '9aede1459667738f05cf4fc46603a4f6',
-    control.ss2tf:                      'e779b8d70205bc1218cc2a4556a66e4b',
-    control.tf2ss:                      '086a3692659b7321c2af126f79f4bc11',
-    control.markov:                     'a4199c54cb50f07c0163d3790739eafe',
-    control.gangof4:                    'f9673ae4c6d26c202060ed4b9ef54800',
-}
-
 # List of keywords that we can skip testing (special cases)
 keyword_skiplist = {
     control.input_output_response: ['method'],
@@ -171,6 +154,9 @@ def test_parameter_docs(module, prefix):
         # Get the signature for the function
         sig = inspect.signature(obj)
 
+	# If first argument is *args, try to use docstring instead
+        sig = _replace_var_positional_with_docstring(sig, doc)
+
         # Go through each parameter and make sure it is in the docstring
         for argname, par in sig.parameters.items():
             # Look for arguments that we can skip
@@ -180,22 +166,11 @@ def test_parameter_docs(module, prefix):
 
             # Check for positional arguments (*arg)
             if par.kind == inspect.Parameter.VAR_POSITIONAL:
-                if obj in function_docstring_hash:
-                    import hashlib
-                    hash = hashlib.md5(
-                        (docstring + source).encode('utf-8')).hexdigest()
-                    if function_docstring_hash[obj] != hash:
-                        _fail(
-                            f"source/docstring for {objname}() modified; "
-                            f"recheck docstring and update hash to "
-                            f"{hash=}")
-                    continue
-
-                # Too complicated to check
                 if f"*{argname}" not in docstring:
-                    _warn(
-                        f"{objname} {argname} has positional arguments; "
-                        "docstring not checked")
+                    _fail(
+                        f"{objname} has undocumented, unbound positional "
+                        f"argument '{argname}'; "
+                        "use docstring signature instead")
                     continue
 
             # Check for keyword arguments (then look at code for parsing)
@@ -621,7 +596,7 @@ def _check_numpydoc_style(obj, doc):
     name = ".".join([obj.__module__.removeprefix("control."), obj.__name__])
 
     # Standard checks for all objects
-    summary = "".join(doc["Summary"])
+    summary = "\n".join(doc["Summary"])
     if len(doc["Summary"]) > 1:
         _warn(f"{name} summary is more than one line")
     if summary and summary[-1] != '.' and re.match(":$", summary) is None:
@@ -666,6 +641,55 @@ def _check_param(param, empty_ok=False, noname_ok=False):
         raise TypeError("unknown object type for {obj}")
 
 
+# Utility function to replace positional signature with docstring signature
+def _replace_var_positional_with_docstring(sig, doc):
+    # If no documentation is available, there is nothing we can do...
+    if doc is None:
+        return sig
+
+    # Check to see if the first argument is positional
+    parameter_items = iter(sig.parameters.items())
+    try:
+        argname, par = next(parameter_items)
+        if par.kind != inspect.Parameter.VAR_POSITIONAL or \
+           (signature := doc["Signature"]) == '':
+            return sig
+    except StopIteration:
+        return sig
+
+    # Try parsing the docstring signature
+    arg_list = []
+    while (1):
+        if (match_fcn := re.match(
+                r"^([\s]*\|[\s]*)*[\w]+\(", signature)) is None:
+            break
+        arg_idx = match_fcn.span(0)[1]
+        while (1):
+            match_arg = re.match(
+                r"[\s]*([\w]+)(,|,\[|\[,|\)|\]\))(,[\s]*|[\s]*[.]{3},[\s]*)*",
+                signature[arg_idx:])
+            if match_arg is None:
+                break
+            else:
+                arg_idx += match_arg.span(0)[1]
+                arg_list.append(match_arg.group(1))
+        signature = signature[arg_idx:]
+    if arg_list == []:
+        return sig
+
+    # Create the new parameter list
+    parameter_list = [
+        inspect.Parameter(arg, inspect.Parameter.POSITIONAL_ONLY)
+        for arg in arg_list]
+
+    # Add any remaining parameters that were in the original signature
+    for argname, par in parameter_items:
+        if argname not in arg_list:
+            parameter_list.append(par)
+
+    # Return the new signature
+    return sig.replace(parameters=parameter_list)
+
 # Utility function to warn with verbose output
 def _info(str, level):
     if verbose > level:
@@ -693,17 +717,17 @@ def simple_function(arg1, arg2, opt1=None, **kwargs):
 
 Failed = pytest.fail.Exception
 
-doc_header = simple_class.simple_function.__doc__
+doc_header = simple_class.simple_function.__doc__ + "\n"
 doc_parameters = "\nParameters\n----------\n"
-doc_arg1 = "\narg1 : int\nArgument 1.\n"
-doc_arg2 = "\narg2 : int\nArgument 2.\n"
-doc_arg2_nospace = "\narg2: int\nArgument 2.\n"
-doc_arg3 = "\narg3 : int\nNon-existent argument 1.\n"
-doc_opt1 = "\nopt1 : int\nKeyword argument 1.\n"
-doc_test = "\ntest : int\nInternal keyword argument 1.\n"
+doc_arg1 = "arg1 : int\n    Argument 1.\n"
+doc_arg2 = "arg2 : int\n    Argument 2.\n"
+doc_arg2_nospace = "arg2: int\n    Argument 2.\n"
+doc_arg3 = "arg3 : int\n    Non-existent argument 1.\n"
+doc_opt1 = "opt1 : int\n    Keyword argument 1.\n"
+doc_test = "test : int\n    Internal keyword argument 1.\n"
 doc_returns = "\nReturns\n-------\n"
-doc_ret = "\nout : int\n"
-doc_ret_nospace = "\nout: int\n"
+doc_ret = "out : int\n"
+doc_ret_nospace = "out: int\n"
 
 @pytest.mark.parametrize("docstring, exception, match", [
     (None, UserWarning, "missing docstring"),
@@ -721,8 +745,8 @@ def simple_function(arg1, arg2, opt1=None, **kwargs):
      doc_returns + doc_ret, Failed, "'test' not documented"),
     (doc_header + doc_parameters + doc_arg1 + doc_arg2_nospace + doc_opt1 +
      doc_test + doc_returns + doc_ret_nospace, UserWarning, "missing space"),
-    (doc_header + doc_arg1 + doc_arg2_nospace + doc_opt1 + doc_test +
-     doc_returns + doc_ret_nospace, Failed, "missing Parameters section"),
+    (doc_header + doc_returns + doc_ret_nospace,
+     Failed, "missing Parameters section"),
     (doc_header, None, ""),
     (doc_header + "\n.. deprecated::", None, ""),
     (doc_header + "\n\n simple_function() is deprecated",
