docstring improvements by sawyerbfuller · Pull Request #804 · python-control/python-control
Per the numpydoc style guide, the "Other Parameters" section should come after the "Returns" section. When processed using numpydoc (eg, for readthedocs), these parameters will get lumped with all other parameters in a single section. But when they are displayed in an interactive session, they are shown in the order listed (so you see the most common parameters, then what the function returns, then other parameters).
For an example, see ct.input_output_response. If you look at the docstring in an interactive session (eg, ?ct.input_output_response in iPython) then you see the the documentation for solve_ivp_method (a rarely used parameter) after the "Returns" section:
Compute the output response of a system to a given input.
Simulate a dynamical system with a given input and return its output
and state values.
Parameters
----------
sys : InputOutputSystem
Input/output system to simulate.
T : array-like
Time steps at which the input is defined; values must be evenly spaced.
U : array-like, list, or number, optional
Input array giving input at each time `T` (default = 0). If a list
is specified, each element in the list will be treated as a portion
of the input and broadcast (if necessary) to match the time vector.
X0 : array-like, list, or number, optional
Initial condition (default = 0). If a list is given, each element
in the list will be flattened and stacked into the initial
condition. If a smaller number of elements are given that the
number of states in the system, the initial condition will be padded
with zeros.
return_x : bool, optional
If True, return the state vector when assigning to a tuple (default =
False). See :func:`forced_response` for more details.
If True, return the values of the state at each time (default = False).
squeeze : bool, optional
If True and if the system has a single output, return the system
output as a 1D array rather than a 2D array. If False, return the
system output as a 2D array even if the system is SISO. Default value
set by config.defaults['control.squeeze_time_response'].
Returns
-------
results : TimeResponseData
Time response represented as a :class:`TimeResponseData` object
containing the following properties:
* time (array): Time values of the output.
* outputs (array): Response of the system. If the system is SISO and
`squeeze` is not True, the array is 1D (indexed by time). If the
system is not SISO or `squeeze` is False, the array is 2D (indexed
by output and time).
* states (array): Time evolution of the state vector, represented as
a 2D array indexed by state and time.
* inputs (array): Input(s) to the system, indexed by input and time.
The return value of the system can also be accessed by assigning the
function to a tuple of length 2 (time, output) or of length 3 (time,
output, state) if ``return_x`` is ``True``. If the input/output
system signals are named, these names will be used as labels for the
time response.
Other parameters
----------------
solve_ivp_method : str, optional
Set the method used by :func:`scipy.integrate.solve_ivp`. Defaults
to 'RK45'.
solve_ivp_kwargs : dict, optional
Pass additional keywords to :func:`scipy.integrate.solve_ivp`.
Raises
------
TypeError
If the system is not an input/output system.
ValueError
If time step does not match sampling time (for discrete time systems).
Notes
-----
1. If a smaller number of initial conditions are given than the number of
states in the system, the initial conditions will be padded with
zeros. This is often useful for interconnected control systems where
the process dynamics are the first system and all other components
start with zero initial condition since this can be specified as
[xsys_0, 0]. A warning is issued if the initial conditions are padded
and and the final listed initial state is not zero.
But if you look at the documentation on readthedocs, you see all of the parameters gathered together: