update backtick guidelines, docstrings, CSS processing

murrayrm · Feb 3, 2025 · Dec 28, 2024 · Dec 28, 2024 · Dec 21, 2024 · Dec 21, 2024
commit 6d5496c92349f39404ca97757135ede5ce9dfa82
diff --git a/control/bdalg.py b/control/bdalg.py
@@ -45,11 +45,11 @@ def series(*sys, **kwargs):
     ----------------
     inputs, outputs : str, or list of str, optional
         List of strings that name the individual signals.  If not given,
-        signal names will be of the form `s[i]` (where `s` is one of `u`,
-        or `y`). See `InputOutputSystem` for more information.
+        signal names will be of the form 's[i]' (where 's' is one of 'u,
+        or 'y'). See `InputOutputSystem` for more information.
     states : str, or list of str, optional
         List of names for system states.  If not given, state names will be
-        of of the form `x[i]` for interconnections of linear systems or
+        of the form 'x[i]' for interconnections of linear systems or
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
@@ -58,8 +58,8 @@ def series(*sys, **kwargs):
     Raises
     ------
     ValueError
-        if `sys2.ninputs` does not equal `sys1.noutputs`
-        if `sys1.dt` is not compatible with `sys2.dt`
+        if ``sys2.ninputs`` does not equal ``sys1.noutputs``
+        if ``sys1.dt`` is not compatible with ``sys2.dt``
 
     See Also
     --------
@@ -116,11 +116,11 @@ def parallel(*sys, **kwargs):
     ----------------
     inputs, outputs : str, or list of str, optional
         List of strings that name the individual signals.  If not given,
-        signal names will be of the form `s[i]` (where `s` is one of `u`,
-        or `y`). See `InputOutputSystem` for more information.
+        signal names will be of the form 's[i'` (where 's' is one of 'u',
+        or 'y'). See `InputOutputSystem` for more information.
     states : str, or list of str, optional
         List of names for system states.  If not given, state names will be
-        of the form `x[i]` for interconnections of linear systems or
+        of the form 'x[i]' for interconnections of linear systems or
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
@@ -129,7 +129,8 @@ def parallel(*sys, **kwargs):
     Raises
     ------
     ValueError
-        if `sys1` and `sys2` do not have the same numbers of inputs and outputs
+        If `sys1` and `sys2` do not have the same numbers of inputs and
+        outputs.
 
     See Also
     --------
@@ -184,11 +185,11 @@ def negate(sys, **kwargs):
     ----------------
     inputs, outputs : str, or list of str, optional
         List of strings that name the individual signals.  If not given,
-        signal names will be of the form `s[i]` (where `s` is one of `u`,
-        or `y`). See `InputOutputSystem` for more information.
+        signal names will be of the form 's[i]' (where 's' is one of 'u',
+        or 'y'). See `InputOutputSystem` for more information.
     states : str, or list of str, optional
         List of names for system states.  If not given, state names will be
-        of of the form `x[i]` for interconnections of linear systems or
+        of of the form 'x[i]' for interconnections of linear systems or
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
@@ -226,10 +227,9 @@ def feedback(sys1, sys2=1, sign=-1, **kwargs):
     ----------
     sys1, sys2 : scalar, array, or `InputOutputSystem`
         I/O systems to combine.
-    sign : scalar
-        The sign of feedback.  `sign` = -1 indicates negative feedback, and
-        `sign` = 1 indicates positive feedback.  `sign` is an optional
-        argument; it assumes a value of -1 if not specified.
+    sign : scalar, optional
+        The sign of feedback.  `sign=-1` indicates negative feedback
+        (default), and `sign=1` indicates positive feedback.
 
     Returns
     -------
@@ -240,11 +240,11 @@ def feedback(sys1, sys2=1, sign=-1, **kwargs):
     ----------------
     inputs, outputs : str, or list of str, optional
         List of strings that name the individual signals.  If not given,
-        signal names will be of the form `s[i]` (where `s` is one of `u`,
-        or `y`). See `InputOutputSystem` for more information.
+        signal names will be of the form 's[i]' (where 's' is one of 'u',
+        or 'y'). See `InputOutputSystem` for more information.
     states : str, or list of str, optional
         List of names for system states.  If not given, state names will be
-        of of the form `x[i]` for interconnections of linear systems or
+        of of the form 'x[i]' for interconnections of linear systems or
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
@@ -333,11 +333,11 @@ def append(*sys, **kwargs):
     ----------------
     inputs, outputs : str, or list of str, optional
         List of strings that name the individual signals.  If not given,
-        signal names will be of the form `s[i]` (where `s` is one of `u`,
-        or `y`). See `InputOutputSystem` for more information.
+        signal names will be of the form 's[i]' (where 's' is one of 'u',
+        or 'y'). See `InputOutputSystem` for more information.
     states : str, or list of str, optional
         List of names for system states.  If not given, state names will be
-        of of the form `x[i]` for interconnections of linear systems or
+        of of the form 'x[i]' for interconnections of linear systems or
         '<subsys_name>.<state_name>' for interconnected nonlinear systems.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
@@ -473,10 +473,10 @@ def combine_tf(tf_array, **kwargs):
     Parameters
     ----------
     tf_array : list of list of TransferFunction or array_like
-        Transfer matrix represented as a two-dimensional array or list-of-lists
-        containing TransferFunction objects. The TransferFunction objects can
-        have multiple outputs and inputs, as long as the dimensions are
-        compatible.
+        Transfer matrix represented as a two-dimensional array or
+        list-of-lists containing TransferFunction objects. The
+        `TransferFunction` objects can have multiple outputs and inputs, as
+        long as the dimensions are compatible.
 
     Returns
     -------
@@ -487,8 +487,8 @@ def combine_tf(tf_array, **kwargs):
     ----------------
     inputs, outputs : str, or list of str, optional
         List of strings that name the individual signals.  If not given,
-        signal names will be of the form `s[i]` (where `s` is one of `u`,
-        or `y`). See `InputOutputSystem` for more information.
+        signal names will be of the form 's[i]' (where 's' is one of 'u',
+        or 'y'). See `InputOutputSystem` for more information.
     name : string, optional
         System name (used for specifying signals). If unspecified, a generic
         name <sys[id]> is generated with a unique integer id.
@@ -535,7 +535,7 @@ def combine_tf(tf_array, **kwargs):
      [array([1.]), array([1.]), array([1.])],
      [array([1.]), array([1.]), array([1, 0])]],
     name='G', outputs=3, inputs=3)
-    
+
     """
     # Find common timebase or raise error
     dt_list = []
@@ -666,10 +666,10 @@ def _ensure_tf(arraylike_or_tf, dt=None):
         Array-like or transfer function.
     dt : None, True or float, optional
         System timebase. 0 (default) indicates continuous
-        time, `True` indicates discrete time with unspecified sampling
+        time, True indicates discrete time with unspecified sampling
         time, positive number is discrete time with specified
-        sampling time, `None` indicates unspecified timebase (either
-        continuous or discrete time). If `None`, timestep is not validated.
+        sampling time, None indicates unspecified timebase (either
+        continuous or discrete time). If None, timestep is not validated.
 
     Returns
     -------

diff --git a/control/canonical.py b/control/canonical.py
@@ -15,8 +15,8 @@
 from .statefbk import ctrb, obsv
 from .statesp import StateSpace, _convert_to_statespace
 
-__all__ = ['canonical_form', 'reachable_form', 'observable_form', 'modal_form',
-           'similarity_transform', 'bdschur']
+__all__ = ['canonical_form', 'reachable_form', 'observable_form',
+           'modal_form', 'similarity_transform', 'bdschur']
 
 
 def canonical_form(xsys, form='reachable'):
@@ -126,10 +126,12 @@ def reachable_form(xsys):
     # Check to make sure inversion was OK.  Note that since we are inverting
     # Wrx and we already checked its rank, this exception should never occur
     if matrix_rank(Tzx) != xsys.nstates:         # pragma: no cover
-        raise ValueError("Transformation matrix singular to working precision.")
+        raise ValueError(
+            "Transformation matrix singular to working precision.")
 
     # Finally, compute the output matrix
-    zsys.C = solve(Tzx.T, xsys.C.T).T  # matrix right division, zsys.C = xsys.C * inv(Tzx)
+    # matrix right division, zsys.C = xsys.C * inv(Tzx)
+    zsys.C = solve(Tzx.T, xsys.C.T).T
 
     return zsys, Tzx
 
@@ -183,7 +185,8 @@ def observable_form(xsys):
     Tzx = solve(Wrz, Wrx)  # matrix left division, Tzx = inv(Wrz) * Wrx
 
     if matrix_rank(Tzx) != xsys.nstates:
-        raise ValueError("Transformation matrix singular to working precision.")
+        raise ValueError(
+            "Transformation matrix singular to working precision.")
 
     # Finally, compute the output matrix
     zsys.B = Tzx @ xsys.B
@@ -206,7 +209,7 @@ def similarity_transform(xsys, T, timescale=1, inverse=False):
     timescale : float, optional
         If present, also rescale the time unit to tau = timescale * t.
     inverse : bool, optional
-        If `False` (default), transform so z = T x.  If `True`, transform
+        If False (default), transform so z = T x.  If True, transform
         so x = T z.
 
     Returns
@@ -270,7 +273,7 @@ def _bdschur_defective(blksizes, eigvals):
 
     Returns
     -------
-    `True` iff Schur blocks are defective.
+    True iff Schur blocks are defective.
 
     blksizes, eigvals are the 3rd and 4th results returned by mb03rd.
     """
@@ -393,7 +396,9 @@ def _bdschur_condmax_search(aschur, tschur, condmax):
             # hit search limit
             return reslower
     else:
-        raise ValueError('bisection failed to converge; pmaxlower={}, pmaxupper={}'.format(pmaxlower, pmaxupper))
+        raise ValueError(
+            "bisection failed to converge; "
+            "pmaxlower={}, pmaxupper={}".format(pmaxlower, pmaxupper))
 
 
 def bdschur(a, condmax=None, sort=None):
@@ -404,7 +409,7 @@ def bdschur(a, condmax=None, sort=None):
     a : (M, M) array_like
         Real matrix to decompose.
     condmax : None or float, optional
-        If `None` (default), use 1/sqrt(eps), which is approximately 1e8.
+        If None (default), use 1/sqrt(eps), which is approximately 1e8.
     sort : {None, 'continuous', 'discrete'}
         Block sorting; see below.
 
@@ -419,7 +424,7 @@ def bdschur(a, condmax=None, sort=None):
 
     Notes
     -----
-    If `sort` is `None`, the blocks are not sorted.
+    If `sort` is None, the blocks are not sorted.
 
     If `sort` is 'continuous', the blocks are sorted according to
     associated eigenvalues.  The ordering is first by real part of
@@ -443,7 +448,8 @@ def bdschur(a, condmax=None, sort=None):
         condmax = np.finfo(np.float64).eps ** -0.5
 
     if not (np.isscalar(condmax) and condmax >= 1.0):
-        raise ValueError('condmax="{}" must be a scalar >= 1.0'.format(condmax))
+        raise ValueError(
+            'condmax="{}" must be a scalar >= 1.0'.format(condmax))
 
     a = np.atleast_2d(a)
     if a.shape[0] == 0 or a.shape[1] == 0:
@@ -491,18 +497,18 @@ def modal_form(xsys, condmax=None, sort=False):
     Parameters
     ----------
     xsys : StateSpace object
-        System to be transformed, with state `x`.
+        System to be transformed, with state ``x``.
     condmax : None or float, optional
-        An upper bound on individual transformations.  If `None`, use
+        An upper bound on individual transformations.  If None, use
         `bdschur` default.
     sort : bool, optional
-        If `False` (default), Schur blocks will not be sorted.  See `bdschur`
+        If False (default), Schur blocks will not be sorted.  See `bdschur`
         for sort order.
 
     Returns
     -------
     zsys : StateSpace object
-        System in modal canonical form, with state `z`.
+        System in modal canonical form, with state ``z``.
     T : (M, M) ndarray
         Coordinate transformation: z = T * x.
 

diff --git a/control/config.py b/control/config.py
@@ -133,6 +133,7 @@ def set_defaults(module, **keywords):
         defaults[module + '.' + key] = val
 
 
+# TODO: allow individual modules and individaul parameters to be reset
 def reset_defaults():
     """Reset configuration values to their default (initial) values.
 
@@ -199,7 +200,7 @@ def _get_param(module, param, argval=None, defval=None, pop=False, last=False):
     parameter for a module based on the default parameter settings and any
     arguments passed to the function.  The precedence order for parameters is
     the value passed to the function (as a keyword), the value from the
-    config.defaults dictionary, and the default value `defval`.
+    `config.defaults` dictionary, and the default value `defval`.
 
     Parameters
     ----------
@@ -214,15 +215,15 @@ def _get_param(module, param, argval=None, defval=None, pop=False, last=False):
     defval : object
         Default value of the parameter to use, if it is not located in the
         `config.defaults` dictionary.  If a dictionary is provided, then
-        `module.param` is used to determine the default value.  Defaults to
+        'module.param' is used to determine the default value.  Defaults to
         None.
     pop : bool, optional
-        If `True` and if argval is a dict, then pop the remove the parameter
+        If True and if argval is a dict, then pop the remove the parameter
         entry from the argval dict after retreiving it.  This allows the use
         of a keyword argument list to be passed through to other functions
         internal to the function being called.
     last : bool, optional
-        If `True`, check to make sure dictionary is empy after processing.
+        If True, check to make sure dictionary is empy after processing.
 
     """
 
@@ -395,7 +396,7 @@ def _process_legacy_keyword(kwargs, oldkey, newkey, newval, warn_oldkey=True):
     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
+        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

diff --git a/control/ctrlplot.py b/control/ctrlplot.py
@@ -148,7 +148,7 @@ class ControlPlot():
         Figure on which the Axes are drawn.
     legend : `matplotlib:.legend.Legend` (instance or ndarray)
         Legend object(s) for the plot.  If more than one legend is
-        included, this will be an array with each entry being either` None`
+        included, this will be an array with each entry being either`` None``
         (for no legend) or a legend object.
 
     """
@@ -194,7 +194,7 @@ def set_plot_title(self, title, frame='axes'):
         fig : Figure, optional
             Matplotlib figure.  Defaults to current figure.
         frame : str, optional
-            Coordinate frame to use for centering: 'axes' (default) or 'figure'.
+            Coordinate frame for centering: 'axes' (default) or 'figure'.
         **kwargs : `matplotlib.pyplot.suptitle` keywords, optional
             Additional keywords (passed to matplotlib).
 
@@ -282,7 +282,7 @@ def pole_zero_subplots(
         Figure to use for creating subplots.
     rcParams : dict
         Override the default parameters used for generating plots.
-        Default is set by config.defaults['ctrlplot.rcParams'].
+        Default is set by `config.defaults['ctrlplot.rcParams']`.
 
     Returns
     -------
@@ -350,7 +350,7 @@ def _process_ax_keyword(
     created with axes of the desired shape.
 
     If `create_axes` is False and a new/empty figure is returned, then axs
-    is an array of the proper shape but `None` for each element.  This allows
+    is an array of the proper shape but None for each element.  This allows
     the calling function to do the actual axis creation (needed for
     curvilinear grids that use the AxisArtist module).
 
@@ -735,7 +735,7 @@ def _get_color(
     Returns
     -------
     color : matplotlib color spec
-        Color to use for this line (or `None` for matplotlib default).
+        Color to use for this line (or None for matplotlib default).
 
     """
     # See if the color was explicitly specified by the user

diff --git a/control/ctrlutil.py b/control/ctrlutil.py
@@ -24,7 +24,7 @@ def unwrap(angle, period=2*math.pi):
     angle : array_like
         Array of angles to be unwrapped.
     period : float, optional
-        Period (defaults to `2*pi`).
+        Period (defaults to ``2*pi``).
 
     Returns
     -------

diff --git a/control/delay.py b/control/delay.py
@@ -8,10 +8,10 @@
 __all__ = ['pade']
 
 def pade(T, n=1, numdeg=None):
-    """
-    Create a linear system that approximates a delay.
+    """Create a linear system that approximates a delay.
 
-    Return the numerator and denominator coefficients of the Pade approximation.
+    Return the numerator and denominator coefficients of the Pade
+    approximation of the given order.
 
     Parameters
     ----------
@@ -20,7 +20,7 @@ def pade(T, n=1, numdeg=None):
     n : positive integer
         Degree of denominator of approximation.
     numdeg : integer, or None (the default)
-        If numdeg is `None`, numerator degree equals denominator degree.
+        If numdeg is None, numerator degree equals denominator degree.
         If numdeg >= 0, specifies degree of numerator.
         If numdeg < 0, numerator degree is n+numdeg.