add documentation for use_numpy_matrix (#323)

control/config.py

@@ -20,7 +20,7 @@
 _use_numpy_matrix = True        # Decide whether to use numpy.marix
 
 def reset_defaults():
-    """Reset configuration values to their default values."""
+    """Reset package configuration values to their default values."""
     global bode_dB; bode_dB = False
     global bode_deg; bode_deg = True
     global bode_Hz; bode_Hz = False
@@ -61,6 +61,22 @@ def use_fbs_defaults():
 
 # Decide whether to use numpy.matrix for state space operations
 def use_numpy_matrix(flag=True, warn=True):
+    """Turn on/off use of Numpy `matrix` class for state space operations.
+
+    Parameters
+    ----------
+    flag : bool
+        If flag is `True` (default), use the Numpy (soon to be deprecated)
+        `matrix` class to represent matrices in the `~control.StateSpace`
+        class and functions.  If flat is `False`, then matrices are represnted
+        by a 2D `ndarray` object.
+
+    warn : bool
+        If flag is `True` (default), issue a warning when turning on the use
+        of the Numpy `matrix` class.  Set `warn` to false to omit display of
+        the warning message.
+
+    """
     if flag and warn:
         warnings.warn("Return type numpy.matrix is soon to be deprecated.",
 	              stacklevel=2)

doc/control.rst

@@ -156,6 +156,7 @@ Utility functions and conversions
     observable_form
     pade
     reachable_form
+    reset_defaults
     sample_system
     ss2tf
     ssdata
@@ -166,3 +167,4 @@ Utility functions and conversions
     unwrap
     use_fbs_defaults
     use_matlab_defaults
+    use_numpy_matrix

doc/conventions.rst

@@ -209,6 +209,8 @@ Functions that can be used to set standard configurations:
 
 .. autosummary::
     :toctree: generated/
-
+
+    reset_defaults
     use_fbs_defaults
     use_matlab_defaults
+    use_numpy_matrix