initial set of devleoper guidelines

Author: murrayrm

control/config.py

@@ -376,15 +376,37 @@ def use_legacy_defaults(version):
     return (major, minor, patch)
 
 
-#
-# Utility function for processing legacy keywords
-#
-# Use this function to handle a legacy keyword that has been renamed.  This
-# function pops the old keyword off of the kwargs dictionary and issues a
-# warning.  If both the old and new keyword are present, a ControlArgument
-# exception is raised.
-#
 def _process_legacy_keyword(kwargs, oldkey, newkey, newval, warn_oldkey=True):
+    """Utility function for processing legacy keywords.
+
+    Use this function to handle a legacy keyword that has been renamed.
+    This function pops the old keyword off of the kwargs dictionary and
+    issues a warning.  If both the old and new keyword are present, a
+    ControlArgument exception is raised.
+
+    Parameters
+    ----------
+    kwargs : dict
+        Dictionary of keword arguments (from function call).
+    oldkey : str
+        Old (legacy) parameter name.
+    newkey : str
+        Current name of the parameter.
+    newval : object
+        Value of the current parameter (from the function signature).
+    warn_oldkey : bool
+        If set to `False`, suppress generation of a warning about using a
+        legacy keyword.  This is useful if you have two versions of a
+        keyword and you want to allow either to be used (see the `cost` and
+        `trajectory_cost` keywords in `flatsys.point_to_point` for an
+        example of this).
+
+    Returns
+    -------
+    val : object
+        Value of the (new) keyword.
+
+    """
     if oldkey in kwargs:
         if warn_oldkey:
             warnings.warn(

control/xferfcn.py

@@ -1439,28 +1439,31 @@ def _convert_to_transfer_function(
         sys, inputs=1, outputs=1, use_prefix_suffix=False):
     """Convert a system to transfer function form (if needed).
 
-    If sys is already a transfer function, then it is returned.  If sys is a
-    state space object, then it is converted to a transfer function and
-    returned.  If sys is a scalar, then the number of inputs and outputs can be
-    specified manually, as in:
+    If `sys` is already a transfer function, then it is returned.  If `sys`
+    is a state space object, then it is converted to a transfer function
+    and returned.  If `sys` is a scalar, then the number of inputs and
+    outputs can be specified manually, as in::
 
-    >>> sys = _convert_to_transfer_function(3.) # Assumes inputs = outputs = 1
-    >>> sys = _convert_to_transfer_function(1., inputs=3, outputs=2)
+      sys = _convert_to_transfer_function(3.) # Assumes inputs = outputs = 1
+      sys = _convert_to_transfer_function(1., inputs=3, outputs=2)
 
-    In the latter example, sys's matrix transfer function is [[1., 1., 1.]
-                                                              [1., 1., 1.]].
+    In the latter example, the matrix transfer function for `sys` is::
 
-    If sys is an array-like type, then it is converted to a constant-gain
+      [[1., 1., 1.]
+       [1., 1., 1.]].
+
+    If `sys` is an array-like type, then it is converted to a constant-gain
     transfer function.
 
     Note: no renaming of inputs and outputs is performed; this should be done
     by the calling function.
 
-    >>> sys = _convert_to_transfer_function([[1., 0.], [2., 3.]])
+    Arrays can also be passed as an argument.  For example::
+
+      sys = _convert_to_transfer_function([[1., 0.], [2., 3.]])
 
-    In this example, the numerator matrix will be
-       [[[1.0], [0.0]], [[2.0], [3.0]]]
-    and the denominator matrix [[[1.0], [1.0]], [[1.0], [1.0]]]
+    will give a system with numerator matrix `[[[1.0], [0.0]], [[2.0],
+    [3.0]]]` and denominator matrix `[[[1.0], [1.0]], [[1.0], [1.0]]]`.
 
     """
     from .statesp import StateSpace

doc/config.rst

@@ -151,6 +151,15 @@ System display parameters
      * 'eval' : system specific, loadable representation
      * 'latex' : latex representation of the object
 
+.. py:data:: iosys.repr_show_count
+   :type: bool
+   :value: True
+
+   If `True`, show the input, output, and state count when using
+   `iosys_repr()` and the 'eval' format.  Otherwise, the input,
+   output, and state values are repressed from the output unless
+   non-generic signal names are present.
+
 .. py:data:: xferfcn.display_format
    :type: str
    :value: 'poly'