10000 improve class documentation in Reference Manual · python-control/python-control@dd61258 · GitHub
[go: up one dir, main page]
Skip to content

Commit dd61258

Browse files
murrayrmmurrayrm
committed
improve class documentation in Reference Manual
1 parent d815462 commit dd61258

15 files changed

+83
-36
lines changed

‎control/ctrlplot.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -685,7 +685,7 @@ def _get_color_offset(ax, color_cycle=None):
685685
686686
Parameters
687687
----------
688-
ax : matplotlib.axes.Axes
688+
ax : `matplotlib.axes.Axes`
689689
Axes containing already plotted lines.
690690
color_cycle : list of matplotlib color specs, optional
691691
Colors to use in plotting lines. Defaults to matplotlib rcParams
@@ -727,7 +727,7 @@ def _get_color(
727727
Offset into the color cycle (for multi-trace plots).
728728
fmt : str, optional
729729
Format string passed to plotting command.
730-
ax : matplotlib.axes.Axes, optional
730+
ax : `matplotlib.axes.Axes`, optional
731731
Axes containing already plotted lines.
732732
lines : list of matplotlib.lines.Line2D, optional
733733
List of plotted lines. If not given, use ax.get_lines().

‎control/descfcn.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -444,7 +444,7 @@ def describing_function_plot(
444444
point_label : str, optional
445445
Formatting string used to label intersection points on the Nyquist
446446
plot. Defaults to "%5.2g @ %-5.2g". Set to None to omit labels.
447-
ax : matplotlib.axes.Axes, optional
447+
ax : `matplotlib.axes.Axes`, optional
448448
The matplotlib axes to draw the figure on. If not specified and
449449
the current figure has a single axes, that axes is used.
450450
Otherwise, a new figure is created.

‎control/freqplot.py

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,15 @@
6767
#
6868

6969
class FrequencyResponseList(list):
70+
"""List of FrequencyResponseData objects with plotting capability.
71+
72+
This class consists of a list of `FrequencyResponseData` objects.
73+
It is a subclass of the Python `list` class, with a `plot` method that
74+
plots the individual `FrequencyResponseData` objects.
75+
76+
"""
7077
def plot(self, *args, plot_type=None, **kwargs):
71-
"""List of FrequencyResponseData objects with plotting capability.
78+
"""Plot a list of frequency responses.
7279
7380
See `FrequencyResponseData.plot` for details.
7481
@@ -150,7 +157,7 @@ def bode_plot(
150157
151158
Other Parameters
152159
----------------
153-
ax : array of matplotlib.axes.Axes, optional
160+
ax : array of `matplotlib.axes.Axes`, optional
154161
The matplotlib axes to draw the figure on. If not specified, the
155162
axes for the current figure are used or, if there is no current
156163
figure with the correct number and shape of axes, a new figure is
@@ -1620,7 +1627,7 @@ def nyquist_plot(
16201627
8 and can be set using `config.defaults['nyquist.arrow_size']`.
16211628
arrow_style : matplotlib.patches.ArrowStyle, optional
16221629
Define style used for Nyquist curve arrows (overrides `arrow_size`).
1623-
ax : matplotlib.axes.Axes, optional
1630+
ax : `matplotlib.axes.Axes`, optional
16241631
The matplotlib axes to draw the figure on. If not specified and
16251632
the current figure has a single axes, that axes is used.
16261633
Otherwise, a new figure is created.
@@ -2401,7 +2408,7 @@ def singular_values_plot(
24012408
24022409
Other Parameters
24032410
----------------
2404-
ax : matplotlib.axes.Axes, optional
2411+
ax : `matplotlib.axes.Axes`, optional
24052412
The matplotlib axes to draw the figure on. If not specified and
24062413
the current figure has a single axes, that axes is used.
24072414
Otherwise, a new figure is created.

‎control/iosys.py

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -322,7 +322,7 @@ def repr_format(self):
322322
323323
Format used in creating the representation for the system:
324324
325-
* 'info' : <IOSystemType:sysname:[inputs] -> [outputs]>
325+
* 'info' : <IOSystemType sysname: [inputs] -> [outputs]>
326326
* 'eval' : system specific, loadable representation
327327
* 'latex' : HTML/LaTeX representation of the object
328328
@@ -537,7 +537,8 @@ def find_inputs(self, name_list):
537537
# Property for getting and setting list of input signals
538538
input_labels = property(
539539
lambda self: list(self.input_index.keys()), # getter
540-
set_inputs) # setter
540+
set_inputs, # setter
541+
doc="List of labels for the input signals.")
541542

542543
def set_outputs(self, outputs, prefix='y'):
543544
"""Set the number/names of the system outputs.
@@ -598,7 +599,8 @@ def find_outputs(self, name_list):
598599
# Property for getting and setting list of output signals
599600
output_labels = property(
600601
lambda self: list(self.output_index.keys()), # getter
601-
set_outputs) # setter
602+
set_outputs, # setter
603+
doc="List of labels for the output signals.")
602604

603605
def set_states(self, states, prefix='x'):
604606
"""Set the number/names of the system states.
@@ -659,7 +661,8 @@ def find_states(self, name_list):
659661
# Property for getting and setting list of state signals
660662
state_labels = property(
661663
lambda self: list(self.state_index.keys()), # getter
662-
set_states) # setter
664+
set_states, # setter
665+
doc="List of labels for the state signals.")
663666

664667
@property
665668
def shape(self):
@@ -942,7 +945,7 @@ def iosys_repr(sys, format=None):
942945
format : str
943946
Format to use in creating the representation:
944947
945-
* 'info' : <IOSystemType:sysname:[inputs] -> [outputs]>
948+
* 'info' : <IOSystemType sysname: [inputs] -> [outputs]>
946949
* 'eval' : system specific, loadable representation
947950
* 'latex' : HTML/LaTeX representation of the object
948951

‎control/lti.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,10 @@
2525
class LTI(InputOutputSystem):
2626
"""Parent class for linear time-invariant system objects.
2727
28-
LTI is the parent to the `StateSpace` and `TransferFunction` child
29-
classes. It contains the number of inputs and outputs, and the timebase
30-
(dt) for the system. This class is not generally accessed directly by
31-
the user.
28+
LTI is the parent to the `FrequencyResponseData`, `StateSpace`, and
29+
`TransferFunction` child classes. It contains the number of inputs and
30+
outputs, and the timebase (dt) for the system. This class is not
31+
generally accessed directly by the user.
3232
3333
See Also
3434
--------
@@ -78,7 +78,7 @@ def __call__(self, x, squeeze=None, warn_infinite=True):
7878
7979
Notes
8080
-----
81-
See `FrequencyResponseData`.__call__`, `StateSpace.__call__`,
81+
See `FrequencyResponseData.__call__`, `StateSpace.__call__`,
8282
`TransferFunction.__call__` for class-specific details.
8383
8484
"""

‎control/nichols.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ def nichols_plot(
6666
6767
Other Parameters
6868
----------------
69-
ax : matplotlib.axes.Axes, optional
69+
ax : `matplotlib.axes.Axes`, optional
7070
The matplotlib axes to draw the figure on. If not specified and
7171
the current figure has a single axes, that axes is used.
7272
Otherwise, a new figure is created.
@@ -191,7 +191,7 @@ def nichols_grid(cl_mags=None, cl_phases=None, line_style='dotted', ax=None,
191191
line_style : string, optional
192192
:doc:`Matplotlib linestyle \
193193
<matplotlib:gallery/lines_bars_and_markers/linestyles>`.
194-
ax : matplotlib.axes.Axes, optional
194+
ax : `matplotlib.axes.Axes`, optional
195195
Axes to add grid to. If None, use `matplotlib.pyplot.gca`.
196196
label_cl_phases : bool, optional
197197
If True, closed-loop phase lines will be labeled.

‎control/phaseplot.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ def phase_plane_plot(
8989
Plot all elements in the given color (use ``plot_<element>`` =
9090
{'color': c} to set the color in one element of the phase
9191
plot (equilpoints, separatrices, streamlines, etc).
92-
ax : matplotlib.axes.Axes, optional
92+
ax : `matplotlib.axes.Axes`, optional
9393
The matplotlib axes to draw the figure on. If not specified and
9494
the current figure has a single axes, that axes is used.
9595
Otherwise, a new figure is created.
@@ -276,7 +276,7 @@ def vectorfield(
276276
dict with key 'args' and value given by a tuple (passed to callable).
277277
color : matplotlib color spec, optional
278278
Plot the vector field in the given color.
279-
ax : matplotlib.axes.Axes
279+
ax : `matplotlib.axes.Axes`, optional
280280
Use the given axes for the plot, otherwise use the current axes.
281281
282282
Returns
@@ -377,7 +377,7 @@ def streamlines(
377377
dict with key 'args' and value given by a tuple (passed to callable).
378378
color : str
379379
Plot the streamlines in the given color.
380-
ax : matplotlib.axes.Axes
380+
ax : `matplotlib.axes.Axes`, optional
381381
Use the given axes for the plot, otherwise use the current axes.
382382
383383
Returns
@@ -498,7 +498,7 @@ def equilpoints(
498498
dict with key 'args' and value given by a tuple (passed to callable).
499499
color : str
500500
Plot the equilibrium points in the given color.
501-
ax : matplotlib.axes.Axes
501+
ax : `matplotlib.axes.Axes`, optional
502502
Use the given axes for the plot, otherwise use the current axes.
503503
504504
Returns
@@ -590,7 +590,7 @@ def separatrices(
590590
separatrices. If a tuple is given, the first element is used as
591591
the color specification for stable separatrices and the second
592592
element for unstable separatrices.
593-
ax : matplotlib.axes.Axes
593+
ax : `matplotlib.axes.Axes`, optional
594594
Use the given axes for the plot, otherwise use the current axes.
595595
596596
Returns

‎control/pzmap.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,7 @@ def pole_zero_plot(
218218
219219
Other Parameters
220220
----------------
221-
ax : matplotlib.axes.Axes, optional
221+
ax : `matplotlib.axes.Axes`, optional
222222
The matplotlib axes to draw the figure on. If not specified and
223223
the current figure has a single axes, that axes is used.
224224
Otherwise, a new figure is created.

‎control/rlocus.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,7 @@ def root_locus_plot(
154154
155155
Other Parameters
156156
----------------
157-
ax : matplotlib.axes.Axes, optional
157+
ax : `matplotlib.axes.Axes`, optional
158158
The matplotlib axes to draw the figure on. If not specified and
159159
the current figure has a single axes, that axes is used.
160160
Otherwise, a new figure is created.

‎control/tests/ctrlplot_test.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -247,10 +247,10 @@ def test_plot_ax_processing(resp_fcn, plot_fcn):
247247
# Make sure that docstring documents ax keyword
248248
if plot_fcn not in legacy_plot_fcns:
249249
if plot_fcn in multiaxes_plot_fcns:
250-
assert "ax : array of matplotlib.axes.Axes, optional" \
250+
assert "ax : array of `matplotlib.axes.Axes`, optional" \
251251
in plot_fcn.__doc__
252252
else:
253-
assert "ax : matplotlib.axes.Axes, optional" in plot_fcn.__doc__
253+
assert "ax : `matplotlib.axes.Axes`, optional" in plot_fcn.__doc__
254254

255255

256256
@pytest.mark.parametrize("resp_fcn, plot_fcn", resp_plot_fcns)

‎control/timeplot.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ def time_response_plot(
110110
add_initial_zero : bool
111111
Add an initial point of zero at the first time point for all
112112
inputs with type 'step'. Default is True.
113-
ax : array of matplotlib.axes.Axes, optional
113+
ax : array of `matplotlib.axes.Axes`, optional
114114
The matplotlib axes to draw the figure on. If not specified, the
115115
axes for the current figure are used or, if there is no current
116116
figure with the correct number and shape of axes, a new figure is

‎doc/_templates/custom-class-template.rst

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,36 @@
55
.. autoclass:: {{ objname }}
66
:members:
77
:show-inheritance:
8-
:inherited-members: list dict
8+
:inherited-members:
99
:special-members:
1010

11+
{% block attributes %}
12+
{% if attributes %}
13+
.. rubric:: {{ _('Attributes') }}
14+
15+
.. autosummary::
16+
:nosignatures:
17+
18+
{% for item in attributes %}
19+
{%- if not item.startswith('_') %}
20+
~{{ name }}.{{ item }}
21+
{%- endif -%}
22+
{%- endfor %}
23+
{% endif %}
24+
{% endblock %}
25+
1126
{% block methods %}
1227
{% if methods %}
1328
.. rubric:: {{ _('Methods') }}
1429

1530
.. autosummary::
1631
:nosignatures:
17-
{% for item in methods %}
18-
{%- if not item.startswith('_') %}
32+
33+
{% for item in members %}
34+
{%- if not item.startswith('_') and item not in attributes %}
35+
~{{ name }}.{{ item }}
36+
{%- endif -%}
37+
{%- if item == '__call__' %}
1938
~{{ name }}.{{ item }}
2039
{%- endif -%}
2140
{%- endfor %}

‎doc/_templates/list-class-template.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ objname }}
6+
:members: plot
7+
:no-inherited-members:
8+
:show-inheritance:

‎doc/classes.rst

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,12 +47,22 @@ These classes are used as the outputs of `_response`, `_map`, and
4747
:nosignatures:
4848

4949
ControlPlot
50-
FrequencyResponseList
50+
FrequencyResponseData
5151
NyquistResponseData
52-
NyquistResponseList
5352
PoleZeroData
54-
PoleZeroList
5553
TimeResponseData
54+
55+
In addition, the following classes are used to store lists of
56+
responses, which can then be plotted using the ``.plot()`` method:
57+
58+
.. autosummary::
59+
:toctree: generated/
60+
:template: list-class-template.rst
61+
:nosignatures:
62+
63+
FrequencyResponseList
64+
NyquistResponseList
65+
PoleZeroList
5666
TimeResponseList
5767

5868
More information on the functions used to create these classes can be

‎doc/config.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ System display parameters
166166
Set the default format used by :func:`iosys_repr` to create the
167167
representation of an :class:`InputOutputSystem`:
168168

169-
* 'info' : <IOSystemType:sysname:[inputs] -> [outputs]>
169+
* 'info' : <IOSystemType sysname: [inputs] -> [outputs]>
170170
* 'eval' : system specific, loadable representation
171171
* 'latex' : latex representation of the object
172172

0 commit comments

Comments
 (0)
0