Skip to content

Commit f79fbe4

Browse files
murrayrmmurrayrm
authored
Fix readthedocs issues (python-control#216)
* updated readthedoc requirements to use generic sphinx and include numpy, scipy, matplotlib * updated docstrings to fix sphinx warning messages and errors * updated documentation style for more consistency
1 parent 26661f6 commit f79fbe4

17 files changed

+205
-405
lines changed

‎control/bdalg.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,12 @@
6262
__all__ = ['series', 'parallel', 'negate', 'feedback', 'append', 'connect']
6363

6464
def series(sys1, *sysn):
65-
"""Return the series connection (... * sys3 *) sys2 * sys1
65+
"""Return the series connection (... \* sys3 \*) sys2 \* sys1
6666
6767
Parameters
6868
----------
6969
sys1: scalar, StateSpace, TransferFunction, or FRD
70-
*sysn: other scalars, StateSpaces, TransferFunctions, or FRDs
70+
sysn: other scalars, StateSpaces, TransferFunctions, or FRDs
7171
7272
Returns
7373
-------

‎control/freqplot.py

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,8 @@
6161
# Bode plot
6262
def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
6363
Plot=True, omega_limits=None, omega_num=None, *args, **kwargs):
64-
"""Bode plot for a system
64+
"""
65+
Bode plot for a system
6566
6667
Plots a Bode plot for the system over a (optional) frequency range.
6768
@@ -84,7 +85,7 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
8485
If Hz=True the limits are in Hz otherwise in rad/s.
8586
omega_num: int
8687
number of samples
87-
*args, **kwargs:
88+
\*args, \**kwargs:
8889
Additional options to matplotlib (color, linestyle, etc)
8990
9091
Returns
@@ -253,7 +254,8 @@ def genZeroCenteredSeries(val_min, val_max, period):
253254
# Nyquist plot
254255
def nyquist_plot(syslist, omega=None, Plot=True, color='b',
255256
labelFreq=0, *args, **kwargs):
256-
"""Nyquist plot for a system
257+
"""
258+
Nyquist plot for a system
257259
258260
Plots a Nyquist plot for the system over a (optional) frequency range.
259261
@@ -267,7 +269,7 @@ def nyquist_plot(syslist, omega=None, Plot=True, color='b',
267269
If True, plot magnitude
268270
labelFreq : int
269271
Label every nth frequency on the plot
270-
*args, **kwargs:
272+
\*args, \**kwargs:
271273
Additional options to matplotlib (color, linestyle, etc)
272274
273275
Returns
@@ -283,6 +285,7 @@ def nyquist_plot(syslist, omega=None, Plot=True, color='b',
283285
--------
284286
>>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
285287
>>> real, imag, freq = nyquist_plot(sys)
288+
286289
"""
287290
# If argument was a singleton, turn it into a list
288291
if (not getattr(syslist, '__iter__', False)):

‎control/lti.py

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -264,7 +264,7 @@ def zero(sys):
264264
return sys.zero()
265265

266266
def damp(sys, doprint=True):
267-
'''
267+
"""
268268
Compute natural frequency, damping ratio, and poles of a system
269269
270270
The function takes 1 or 2 parameters
@@ -285,24 +285,26 @@ def damp(sys, doprint=True):
285285
poles: array
286286
Pole locations
287287
288-
289288
Algorithm
290-
--------
291-
If the system is continuous,
292-
wn = abs(poles)
293-
Z = -real(poles)/poles.
289+
---------
290+
If the system is continuous,
291+
wn = abs(poles)
292+
Z = -real(poles)/poles.
293+
294+
If the system is discrete, the discrete poles are mapped to their
295+
equivalent location in the s-plane via
294296
295-
If the system is discrete, the discrete poles are mapped to their
296-
equivalent location in the s-plane via
297-
s = log10(poles)/dt
298-
and
299-
wn = abs(s)
300-
Z = -real(s)/wn.
297+
s = log10(poles)/dt
298+
299+
and
300+
301+
wn = abs(s)
302+
Z = -real(s)/wn.
301303
302304
See Also
303305
--------
304306
pole
305-
'''
307+
"""
306308
wn, damping, poles = sys.damp()
307309
if doprint:
308310
print('_____Eigenvalue______ Damping___ Frequency_')

‎control/margins.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ def stability_margins(sysdata, returnall=False, epsw=0.0):
129129
wg: float or array_like
130130
Frequency for gain margin (at phase crossover, phase = -180 degrees)
131131
wp: float or array_like
132-
Frequency for phase margin (at gain crossover, gain = 0 dB)
132+
Frequency for phase margin (at gain crossover, gain = 1)
133133
ws: float or array_like
134134
Frequency for stability margin (complex gain closest to -1)
135135
"""
@@ -343,12 +343,12 @@ def margin(*args):
343343
wg: float
344344
Frequency for gain margin (at phase crossover, phase = -180 degrees)
345345
wp: float
346-
Frequency for phase margin (at gain crossover, gain = 0 dB)
346+
Frequency for phase margin (at gain crossover, gain = 1)
347347
348348
Margins are calculated for a SISO open-loop system.
349349
350350
If there is more than one gain crossover, the one at the smallest
351-
margin (deviation from gain=0dB), in absolute sense, is
351+
margin (deviation from gain = 1), in absolute sense, is
352352
returned. Likewise the smallest phase margin (in absolute sense)
353353
is returned.
354354

‎control/modelsimp.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -125,8 +125,8 @@ def modred(sys, ELIM, method='matchdc'):
125125
Raises
126126
------
127127
ValueError
128-
* if `method` is not either ``'matchdc'`` or ``'truncate'``
129-
* if eigenvalues of `sys.A` are not all in left half plane
128+
- if `method` is not either ``'matchdc'`` or ``'truncate'``
129+
- if eigenvalues of `sys.A` are not all in left half plane
130130
(`sys` must be stable)
131131
132132
Examples

‎control/robust.py

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -336,14 +336,16 @@ def mixsyn(g,w1=None,w2=None,w3=None):
336336
Returns
337337
-------
338338
k: synthesized controller; StateSpace object
339-
cl: closed system mapping evaluation inputs to evaluation outputs; if p is the augmented plant, with
340-
[z] = [p11 p12] [w], then cl is the system from w->z with u=-k*y. StateSpace object.
339+
cl: closed system mapping evaluation inputs to evaluation outputs; if
340+
p is the augmented plant, with
341+
[z] = [p11 p12] [w],
341342
[y] [p21 g] [u]
343+
then cl is the system from w->z with u=-k*y. StateSpace object.
342344
343345
info: tuple with entries, in order,
344-
gamma: scalar; H-infinity norm of cl
345-
rcond: array; estimates of reciprocal condition numbers
346-
computed during synthesis. See hinfsyn for details
346+
- gamma: scalar; H-infinity norm of cl
347+
- rcond: array; estimates of reciprocal condition numbers
348+
computed during synthesis. See hinfsyn for details
347349
348350
If a weighting w is scalar, it will be replaced by I*w, where I is
349351
ny-by-ny for w1 and w3, and nu-by-nu for w2.

‎control/statefbk.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
def place(A, B, p):
5353
"""Place closed loop eigenvalues
5454
K = place(A, B, p)
55+
5556
Parameters
5657
----------
5758
A : 2-d array

‎control/statesp.py

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -414,7 +414,8 @@ def horner(self, s):
414414

415415
# Method for generating the frequency response of the system
416416
def freqresp(self, omega):
417-
"""Evaluate the system's transfer func. at a list of freqs, omega.
417+
"""
418+
Evaluate the system's transfer func. at a list of freqs, omega.
418419
419420
mag, phase, omega = self.freqresp(omega)
420421
@@ -427,22 +428,22 @@ def freqresp(self, omega):
427428
428429
G(exp(j*omega*dt)) = mag*exp(j*phase).
429430
430-
Inputs:
431+
Inputs
431432
------
432-
omega: A list of frequencies in radians/sec at which the system
433-
should be evaluated. The list can be either a python list
434-
or a numpy array and will be sorted before evaluation.
433+
omega: A list of frequencies in radians/sec at which the system
434+
should be evaluated. The list can be either a python list
435+
or a numpy array and will be sorted before evaluation.
435436
436-
Returns:
437+
Returns
437438
-------
438-
mag: The magnitude (absolute value, not dB or log10) of the system
439-
frequency response.
439+
mag: The magnitude (absolute value, not dB or log10) of the system
440+
frequency response.
440441
441-
phase: The wrapped phase in radians of the system frequency
442-
response.
442+
phase: The wrapped phase in radians of the system frequency
443+
response.
443444
444-
omega: The list of sorted frequencies at which the response
445-
was evaluated.
445+
omega: The list of sorted frequencies at which the response
446+
was evaluated.
446447
447448
"""
448449

‎doc-requirements.txt

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
numpydoc==0.4
2-
mock==1.0.1
3-
# install sphinx from git to get patched version
4-
# (fixes bug in autosummary where tables do not display)
5-
-e git://github.com/sphinx-doc/sphinx.git@stable#egg=Sphinx-origin_stable
6-
1+
numpy
2+
scipy
3+
matplotlib
4+
numpydoc

‎doc/Makefile

Lines changed: 10 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,20 @@
1-
# Makefile for Sphinx documentation
1+
# Minimal makefile for Sphinx documentation
22
#
33

44
# You can set these variables from the command line.
55
SPHINXOPTS =
66
SPHINXBUILD = sphinx-build
7-
PAPER =
7+
SPHINXPROJ = PythonControlLibrary
8+
SOURCEDIR = .
89
BUILDDIR = _build
910

10-
# Internal variables.
11-
PAPEROPT_a4 = -D latex_paper_size=a4
12-
PAPEROPT_letter = -D latex_paper_size=letter
13-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14-
15-
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
16-
11+
# Put it first so that "make" without argument is like "make help".
1712
help:
18-
@echo "Please use \`make <target>' where <target> is one of"
19-
@echo " html to make standalone HTML files"
20-
@echo " dirhtml to make HTML files named index.html in directories"
21-
@echo " singlehtml to make a single large HTML file"
22-
@echo " pickle to make pickle files"
23-
@echo " json to make JSON files"
24-
@echo " htmlhelp to make HTML files and a HTML help project"
25-
@echo " qthelp to make HTML files and a qthelp project"
26-
@echo " devhelp to make HTML files and a Devhelp project"
27-
@echo " epub to make an epub"
28-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
29-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
30-
@echo " text to make text files"
31-
@echo " man to make manual pages"
32-
@echo " changes to make an overview of all changed/added/deprecated items"
33-
@echo " linkcheck to check all external links for integrity"
34-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
35-
36-
clean:
37-
-rm -rf $(BUILDDIR)/* generated/*
38-
39-
html:
40-
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
41-
@echo
42-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
43-
44-
dirhtml:
45-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
46-
@echo
47-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
48-
49-
singlehtml:
50-
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
51-
@echo
52-
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
53-
54-
pickle:
55-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
56-
@echo
57-
@echo "Build finished; now you can process the pickle files."
58-
59-
json:
60-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
61-
@echo
62-
@echo "Build finished; now you can process the JSON files."
63-
64-
htmlhelp:
65-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
66-
@echo
67-
@echo "Build finished; now you can run HTML Help Workshop with the" \
68-
".hhp project file in $(BUILDDIR)/htmlhelp."
69-
70-
qthelp:
71-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
72-
@echo
73-
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
74-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
75-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PythonControl.qhcp"
76-
@echo "To view the help file:"
77-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PythonControl.qhc"
78-
79-
devhelp:
80-
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
81-
@echo
82-
@echo "Build finished."
83-
@echo "To view the help file:"
84-
@echo "# mkdir -p $$HOME/.local/share/devhelp/PythonControl"
85-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PythonControl"
86-
@echo "# devhelp"
87-
88-
epub:
89-
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
90-
@echo
91-
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
92-
93-
latex:
94-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
95-
@echo
96-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
97-
@echo "Run \`make' in that directory to run these through (pdf)latex" \
98-
"(use \`make latexpdf' here to do that automatically)."
99-
100-
latexpdf:
101-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
102-
@echo "Running LaTeX files through pdflatex..."
103-
make -C $(BUILDDIR)/latex all-pdf
104-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
105-
106-
text:
107-
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
108-
@echo
109-
@echo "Build finished. The text files are in $(BUILDDIR)/text."
110-
111-
man:
112-
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
113-
@echo
114-
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
115-
116-
changes:
117-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
118-
@echo
119-
@echo "The overview file is in $(BUILDDIR)/changes."
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
12014

121-
linkcheck:
122-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
123-
@echo
124-
@echo "Link check complete; look for any errors in the above output " \
125-
"or in $(BUILDDIR)/linkcheck/output.txt."
15+
.PHONY: help Makefile
12616

127-
doctest:
128-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
129-
@echo "Testing of doctests in the sources finished, look at the " \
130-
"results in $(BUILDDIR)/doctest/output.txt."
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/classes.rst

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
LTI system classes
2-
==================
3-
1+
.. _class-ref:
42
.. currentmodule:: control
53

4+
******************
5+
LTI system classes
6+
******************
7+
68
The classes listed below are used to represent models of linear time-invariant
79
(LTI) systems. They are usually created from factory functions such as
810
:func:`tf` and :func:`ss`, so the user should normally not need to instantiate
@@ -14,3 +16,4 @@ these directly.
1416
TransferFunction
1517
StateSpace
1618
FRD
19+

0 commit comments

Comments
 (0)