add special processing for sys

murrayrm · murrayrm · commit 3de0ee7fc410 · 2025-02-02T21:14:17.000-08:00
diff --git a/control/frdata.py b/control/frdata.py
@@ -938,12 +938,12 @@ def to_pandas(self):
 def _convert_to_frd(sys, omega, inputs=1, outputs=1):
     """Convert a system to frequency response data form (if needed).
 
-    If sys is already an frd, and its frequency range matches or
-    overlaps the range given in omega then it is returned.  If sys is
-    another LTI object or a transfer function, then it is converted to
-    a frequency response data at the specified omega. If sys is a
-    scalar, then the number of inputs and outputs can be specified
-    manually, as in:
+    If `sys` is already a frequency response data object, and its
+    frequency range matches or overlaps the range given in omega then
+    it is returned.  If `sys` is another LTI object or a transfer
+    function, then it is converted to a frequency response data at the
+    specified omega. If `sys` is a scalar, then the number of inputs and
+    outputs can be specified manually, as in:
 
     >>> import numpy as np
     >>> from control.frdata import _convert_to_frd
diff --git a/control/lti.py b/control/lti.py
@@ -541,7 +541,7 @@ def frequency_response(
         frequency.  If `squeeze` is True then single-dimensional axes are
         removed.
 
-        Returns a list of `FrequencyResponseData` objects if sys is
+        Returns a list of `FrequencyResponseData` objects if `sys` is
         a list of systems.
 
     Other Parameters
diff --git a/control/matlab/wrappers.py b/control/matlab/wrappers.py
@@ -29,7 +29,7 @@ def bode(*args, **kwargs):
     sys : LTI, or list of LTI
         System for which the Bode response is plotted and give. Optionally
         a list of systems can be entered, or several systems can be
-        specified (i.e. several parameters). The sys arguments may also be
+        specified (i.e. several parameters). The `sys` arguments may also be
         interspersed with format strings. A frequency argument (array_like)
         may also be added (see Examples).
     omega : array
diff --git a/control/modelsimp.py b/control/modelsimp.py
@@ -255,12 +255,12 @@ def _expand_key(key):
 
 
 def balanced_reduction(sys, orders, method='truncate', alpha=None):
-    """Balanced reduced order model of sys of a given order.
+    """Balanced reduced order model of system of a given order.
 
-    States are eliminated based on Hankel singular value.
-    If sys has unstable modes, they are removed, the
-    balanced realization is done on the stable part, then
-    reinserted in accordance with the reference below.
+    States are eliminated based on Hankel singular value.  If `sys` has
+    unstable modes, they are removed, the balanced realization is done on
+    the stable part, then reinserted in accordance with the reference
+    below.
 
     Reference: Hsu,C.S., and Hou,D., 1991,
     Reducing unstable linear control systems via real Schur transformation.
diff --git a/control/nlsys.py b/control/nlsys.py
@@ -584,7 +584,7 @@ class InterconnectedSystem(NonlinearIOSystem):
     """Interconnection of a set of input/output systems.
 
     This class is used to implement a system that is an interconnection of
-    input/output systems.  The sys consists of a collection of subsystems
+    input/output systems.  The system consists of a collection of subsystems
     whose inputs and outputs are connected via a connection map.  The overall
     system inputs and outputs are subsets of the subsystem inputs and outputs.
 
diff --git a/control/sisotool.py b/control/sisotool.py
@@ -41,19 +41,19 @@ def sisotool(sys, initial_gain=None, xlim_rlocus=None, ylim_rlocus=None,
     Parameters
     ----------
     sys : LTI object
-        Linear input/output systems. If sys is SISO, use the same system for
-        the root locus and step response. If it is desired to see a different
-        step response than feedback(K*sys,1), such as a disturbance response,
-        sys can be provided as a two-input, two-output system (e.g. by using
-        `bdgalg.connect' or `iosys.interconnect`). For two-input,
-        two-output system, sisotool inserts the negative of the selected gain
-        K between the first output and first input and uses the second input
-        and output for computing the step response. To see the disturbance
-        response, configure your plant to have as its second input the
-        disturbance input.  To view the step response with a feedforward
-        controller, give your plant two identical inputs, and sum your
-        feedback controller and your feedforward controller and multiply them
-        into your plant's second input. It is also possible to accomodate a
+        Linear input/output systems. If `sys` is SISO, use the same system
+        for the root locus and step response. If it is desired to see a
+        different step response than ``feedback(K*sys, 1)``, such as a
+        disturbance response, `sys` can be provided as a two-input,
+        two-output system. For two-input, two-output system, sisotool
+        inserts the negative of the selected gain `K` between the first
+        output and first input and uses the second input and output for
+        computing the step response. To see the disturbance response,
+        configure your plant to have as its second input the disturbance
+        input.  To view the step response with a feedforward controller,
+        give your plant two identical inputs, and sum your feedback
+        controller and your feedforward controller and multiply them into
+        your plant's second input. It is also possible to accomodate a
         system with a gain in the feedback.
     initial_gain : float, optional
         Initial gain to use for plotting root locus. Defaults to 1
diff --git a/control/statesp.py b/control/statesp.py
@@ -164,7 +164,7 @@ def __init__(self, *args, **kwargs):
         are matrices or equivalent objects.  To create a discrete-time
         system, use StateSpace(A, B, C, D, dt) where `dt` is the sampling
         time (or True for unspecified sampling time).  To call the copy
-        constructor, call StateSpace(sys), where sys is a StateSpace
+        constructor, call ``StateSpace(sys)``, where `sys` is a `StateSpace`
         object.
 
         See `StateSpace` and `ss` for more information.
@@ -1639,7 +1639,7 @@ def ss(*args, **kwargs):
     ``ss(sys)``
 
         Convert a linear system into space system form. Always creates a
-        new system, even if sys is already a state space system.
+        new system, even if `sys` is already a state space system.
 
     ``ss(A, B, C, D)``
 
@@ -1808,7 +1808,7 @@ def tf2io(*args, **kwargs):
     ``tf2io(sys)``
 
         Convert a linear system into space space form. Always creates
-        a new system, even if sys is already a `StateSpace` object.
+        a new system, even if `sys` is already a `StateSpace` object.
 
     ``tf2io(num, den)``
 
@@ -2371,9 +2371,9 @@ def _f2s(f):
 def _convert_to_statespace(sys, use_prefix_suffix=False, method=None):
     """Convert a system to state space form (if needed).
 
-    If sys is already a state space, then it is returned.  If sys is a
-    transfer function object, then it is converted to a state space and
-    returned.
+    If `sys` is already a state space object, then it is returned.  If
+    `sys` is a transfer function object, then it is converted to a state
+    space and returned.
 
     Note: no renaming of inputs and outputs is performed; this should be done
     by the calling function.
diff --git a/control/timeresp.py b/control/timeresp.py
@@ -1330,15 +1330,15 @@ def step_response(
         I/O system(s) for which step response is computed.
 
     T : array_like or float, optional
-        Time vector, or simulation time duration if a number. If T is not
+        Time vector, or simulation time duration if a number. If `T` is not
         provided, an attempt is made to create it automatically from the
-        dynamics of sys. If sys is continuous time, the time increment dt
-        is chosen small enough to show the fastest mode, and the simulation
-        time period tfinal long enough to show the slowest mode, excluding
-        poles at the origin and pole-zero cancellations. If this results in
-        too many time steps (>5000), dt is reduced. If sys is discrete time,
-        only tfinal is computed, and final is reduced if it requires too
-        many simulation steps.
+        dynamics of the system. If the system continuous time, the time
+        increment dt is chosen small enough to show the fastest mode, and
+        the simulation time period tfinal long enough to show the slowest
+        mode, excluding poles at the origin and pole-zero cancellations. If
+        this results in too many time steps (>5000), dt is reduced. If the
+        system is discrete time, only tfinal is computed, and final is
+        reduced if it requires too many simulation steps.
 
     X0 : array_like or float, optional
         Initial condition (default = 0).  This can be used for a nonlinear
@@ -1357,8 +1357,9 @@ def step_response(
         If system is a nonlinear I/O system, set parameter values.
 
     T_num : int, optional
-        Number of time steps to use in simulation if T is not provided as an
-        array (autocomputed if not given); ignored if sys is discrete time.
+        Number of time steps to use in simulation if `T` is not provided as
+        an array (autocomputed if not given); ignored if the system is
+        discrete time.
 
     transpose : bool, optional
         If True, transpose all input and output arrays (for backward
@@ -1484,8 +1485,7 @@ def step_response(
 
 def step_info(sysdata, T=None, T_num=None, yfinal=None, params=None,
               SettlingTimeThreshold=0.02, RiseTimeLimits=(0.1, 0.9)):
-    """
-    Step response characteristics (rise time, settling time, etc).
+    """Step response characteristics (rise time, settling time, etc).
 
     Parameters
     ----------
@@ -1497,8 +1497,8 @@ def step_info(sysdata, T=None, T_num=None, yfinal=None, params=None,
         autocomputed if not given, see `step_response` for more detail).
         Required, if sysdata is a time series of response data.
     T_num : int, optional
-        Number of time steps to use in simulation if T is not provided as an
-        array; autocomputed if not given; ignored if sysdata is a
+        Number of time steps to use in simulation if `T` is not provided as
+        an array; autocomputed if not given; ignored if sysdata is a
         discrete-time system or a time series or response data.
     yfinal : scalar or array_like, optional
         Steady-state response. If not given, sysdata.dcgain() is used for
@@ -1586,6 +1586,7 @@ def step_info(sysdata, T=None, T_num=None, yfinal=None, params=None,
     Peak: 1.209
     PeakTime: 4.242
     SteadyStateValue: -1.0
+
     """
     from .nlsys import NonlinearIOSystem
     from .statesp import StateSpace
@@ -1743,9 +1744,10 @@ def initial_response(
         to None to not trim outputs.
 
     T_num : int, optional
-        Number of time steps to use in simulation if T is not provided as an
-        array (autocomputed if not given); ignored if sys is discrete time.
-
+        Number of time steps to use in simulation if `T` is not provided as
+        an array (autocomputed if not given); ignored if the system is
+        discrete time.
+    
     params : dict, optional
         If system is a nonlinear I/O system, set parameter values.
 
@@ -1862,8 +1864,9 @@ def impulse_response(
         specified, all outputs are reported.
 
     T_num : int, optional
-        Number of time steps to use in simulation if T is not provided as an
-        array (autocomputed if not given); ignored if sys is discrete time.
+        Number of time steps to use in simulation if `T` is not provided as
+        an array (autocomputed if not given); ignored if the system is
+        discrete time.
 
     transpose : bool, optional
         If True, transpose all input and output arrays (for backward
diff --git a/control/xferfcn.py b/control/xferfcn.py
@@ -163,13 +163,13 @@ def __init__(self, *args, **kwargs):
 
         Construct a transfer function.
 
-        The default constructor is TransferFunction(num, den), where num and
-        den are 2D arrays of arrays containing polynomial coefficients.
-        To create a discrete-time transfer function, use TransferFunction(num,
-        den, dt) where 'dt' is the sampling time (or True for unspecified
-        sampling time).  To call the copy constructor, call
-        TransferFunction(sys), where sys is a TransferFunction object
-        (continuous or discrete).
+        The default constructor is TransferFunction(num, den), where num
+        and den are 2D arrays of arrays containing polynomial coefficients.
+        To create a discrete-time transfer function, use
+        ``TransferFunction(num, den, dt)`` where `dt` is the sampling time
+        (or True for unspecified sampling time).  To call the copy
+        constructor, call ``TransferFunction(sys)``, where `sys` is a
+        TransferFunction object (continuous or discrete).
 
         See `TransferFunction` and `tf` for more information.
 
@@ -1631,7 +1631,7 @@ def tf(*args, **kwargs):
     ``tf(sys)``
 
         Convert a linear system into transfer function form. Always creates
-        a new system, even if sys is already a `TransferFunction` object.
+        a new system, even if `sys` is already a `TransferFunction` object.
 
     ``tf(num, den)``
 
diff --git a/doc/conf.py b/doc/conf.py
@@ -107,6 +107,9 @@
      'python': ('https://docs.python.org/3/', None),
      }
 
+# Don't generate external links to (local) keywords
+intersphinx_disabled_reftypes = ["py:keyword"]
+
 # If this is True, todo and todolist produce output, else they produce nothing.
 # The default is False.
 todo_include_todos = True
@@ -220,7 +223,7 @@ def linkcode_resolve(domain, info):
     else:                       # specific version
         return base_url + "%s/control/%s%s" % (version, fn, linespec)
 
-# Don't automaticall show all members of class in Methods & Attributes section
+# Don't automatically show all members of class in Methods & Attributes section
 numpydoc_show_class_members = False
 
 # Don't create a Sphinx TOC for the lists of class methods and attributes
@@ -294,3 +297,16 @@ def linkcode_resolve(domain, info):
 import control.phaseplot as pp
 ct.reset_defaults()
 """
+
+# -- Customization for python-control ----------------------------------------
+#
+# This code does custom processing of docstrings for the python-control
+# package.
+
+def process_docstring(app, what, name, obj, options, lines):
+    # Loop through each line in docstring and replace `sys` with :code:`sys`
+    for i in range(len(lines)):
+        lines[i] = lines[i].replace("`sys`", ":code:`sys`")
+
+def setup(app):
+    app.connect('autodoc-process-docstring', process_docstring)
diff --git a/doc/develop.rst b/doc/develop.rst
@@ -188,7 +188,8 @@ System-creating commands:
 
 System arguments:
 
-* `sys` when an argument is a single input/output system (e.g. `bandwidth`).
+* :code:`sys` when an argument is a single input/output system
+  (e.g. `bandwidth`).
 
 * `syslist` when an argument is a list of systems (e.g.,
   `interconnect`).  A single system should also be OK.
@@ -253,6 +254,14 @@ guidelines:
     bolder type, so that it is easier to see what things you can click
     on to get more information.
 
+  - By default, the string \`sys\` in docstrings would normally
+    generate a link to the :mod:`sys` Python module.  To avoid this,
+    `conf.py` includes code that converts \`sys\` in docstrings to
+    \:code\:\`sys`, which renders as :code:`sys` (code style, with no
+    link).  In ``.rst`` files, this construction should be done
+    manually, since ``.rst`` files are not pre-processed as a
+    docstring.
+
 * Use double backticks for inline code, such as a Python code fragments.
 
   - In principle single backticks might actually work OK given the way
diff --git a/doc/iosys.rst b/doc/iosys.rst
@@ -653,7 +653,7 @@ can be created with the command::
 
   ctrl, clsys = ct.create_statefbk_iosystem(sys, K)
 
-where `sys` is the process dynamics and `K` is the state feedback gain
+where :code:`sys` is the process dynamics and `K` is the state feedback gain
 (e.g., from LQR).  The function returns the controller `ctrl` and the
 closed loop systems `clsys`, both as I/O systems.  The input to the
 controller is the vector of desired states :math:`x_\text{d}`, desired
diff --git a/doc/optimal.rst b/doc/optimal.rst
@@ -131,7 +131,7 @@ by using the :func:`~optimal.solve_ocp` function::
 
   res = opt.solve_ocp(sys, timepts, X0, cost, constraints)
 
-The `sys` parameter should be an :class:`InputOutputSystem` and the
+The :code:`sys` parameter should be an :class:`InputOutputSystem` and the
 `timepts` parameter should represent a time vector that gives the list
 of times at which the cost and constraints should be evaluated (the
 time points need not be uniformly spaced).
diff --git a/doc/statesp.rst b/doc/statesp.rst
@@ -131,7 +131,7 @@ several forms:
   * ``K, S, E = ct.lqr(A, B, Q, R)``
   * ``K, S, E = ct.lqr(A, B, Q, R, N)``
 
-If `sys` is a discrete-time system, the first two forms will compute
+If :code:`sys` is a discrete-time system, the first two forms will compute
 the discrete-time optimal controller.  For the second two forms, the
 :func:`dlqr` function can be used to compute the discrete-time optimal
 controller.  Additional arguments and details are given on the
diff --git a/doc/stochastic.rst b/doc/stochastic.rst
@@ -180,8 +180,8 @@ called in several forms:
   * ``L, P, E = lqe(A, G, C, QN, RN)``
   * ``L, P, E = lqe(A, G, C, QN, RN, NN)``
 
-where `sys` is an :class:`LTI` object, and `A`, `G`, `C`, `QN`, `RN`,
-and `NN` are 2D arrays of appropriate dimension.  If `sys` is a
+where :code:`sys` is an :class:`LTI` object, and `A`, `G`, `C`, `QN`, `RN`,
+and `NN` are 2D arrays of appropriate dimension.  If :code:`sys` is a
 discrete-time system, the first two forms will compute the discrete
 time optimal controller.  For the second two forms, the :func:`dlqr`
 function can be used.  Additional arguments and details are given on
