python-control · murrayrm · Jul 4, 2018 · Jul 4, 2018 · Jul 4, 2018 · Jul 4, 2018
diff --git a/control/bdalg.py b/control/bdalg.py
@@ -62,12 +62,12 @@
 __all__ = ['series', 'parallel', 'negate', 'feedback', 'append', 'connect']
 
 def series(sys1, *sysn):
-    """Return the series connection (... * sys3 *) sys2 * sys1
+    """Return the series connection (... \* sys3 \*) sys2 \* sys1
 
     Parameters
     ----------
     sys1: scalar, StateSpace, TransferFunction, or FRD
-    *sysn: other scalars, StateSpaces, TransferFunctions, or FRDs
+    sysn: other scalars, StateSpaces, TransferFunctions, or FRDs
 
     Returns
     -------

diff --git a/control/freqplot.py b/control/freqplot.py
@@ -61,7 +61,8 @@
 # Bode plot
 def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
         Plot=True, omega_limits=None, omega_num=None, *args, **kwargs):
-    """Bode plot for a system
+    """
+    Bode plot for a system
 
     Plots a Bode plot for the system over a (optional) frequency range.
 
@@ -84,7 +85,7 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
         If Hz=True the limits are in Hz otherwise in rad/s.
     omega_num: int
         number of samples
-    *args, **kwargs:
+    \*args, \**kwargs:
         Additional options to matplotlib (color, linestyle, etc)
 
     Returns
@@ -253,7 +254,8 @@ def genZeroCenteredSeries(val_min, val_max, period):
 # Nyquist plot
 def nyquist_plot(syslist, omega=None, Plot=True, color='b',
                  labelFreq=0, *args, **kwargs):
-    """Nyquist plot for a system
+    """
+    Nyquist plot for a system
 
     Plots a Nyquist plot for the system over a (optional) frequency range.
 
@@ -267,7 +269,7 @@ def nyquist_plot(syslist, omega=None, Plot=True, color='b',
         If True, plot magnitude
     labelFreq : int
         Label every nth frequency on the plot
-    *args, **kwargs:
+    \*args, \**kwargs:
         Additional options to matplotlib (color, linestyle, etc)
 
     Returns
@@ -283,6 +285,7 @@ def nyquist_plot(syslist, omega=None, Plot=True, color='b',
     --------
     >>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
     >>> real, imag, freq = nyquist_plot(sys)
+
     """
     # If argument was a singleton, turn it into a list
     if (not getattr(syslist, '__iter__', False)):

diff --git a/control/lti.py b/control/lti.py
@@ -264,7 +264,7 @@ def zero(sys):
     return sys.zero()
 
 def damp(sys, doprint=True):
-    '''
+    """
     Compute natural frequency, damping ratio, and poles of a system
 
     The function takes 1 or 2 parameters
@@ -285,24 +285,26 @@ def damp(sys, doprint=True):
     poles: array
         Pole locations
 
-
     Algorithm
-    --------
-        If the system is continuous,
-           wn = abs(poles)
-           Z  = -real(poles)/poles.
+    ---------
+    If the system is continuous,
+        wn = abs(poles)
+        Z  = -real(poles)/poles.
+
+    If the system is discrete, the discrete poles are mapped to their
+    equivalent location in the s-plane via
 
-        If the system is discrete, the discrete poles are mapped to their
-        equivalent location in the s-plane via
-           s = log10(poles)/dt
-        and
-          wn = abs(s)
-          Z = -real(s)/wn.
+        s = log10(poles)/dt
+
+    and
+
+        wn = abs(s)
+        Z = -real(s)/wn.
 
     See Also
     --------
     pole
-    '''
+    """
     wn, damping, poles = sys.damp()
     if doprint:
         print('_____Eigenvalue______ Damping___ Frequency_')

diff --git a/control/margins.py b/control/margins.py
@@ -129,7 +129,7 @@ def stability_margins(sysdata, returnall=False, epsw=0.0):
     wg: float or array_like
         Frequency for gain margin (at phase crossover, phase = -180 degrees)
     wp: float or array_like
-        Frequency for phase margin (at gain crossover, gain = 0 dB)
+        Frequency for phase margin (at gain crossover, gain = 1)
     ws: float or array_like
         Frequency for stability margin (complex gain closest to -1)
     """
@@ -343,12 +343,12 @@ def margin(*args):
     wg: float
         Frequency for gain margin (at phase crossover, phase = -180 degrees)
     wp: float
-        Frequency for phase margin (at gain crossover, gain = 0 dB)
+        Frequency for phase margin (at gain crossover, gain = 1)
 
     Margins are calculated for a SISO open-loop system.
 
     If there is more than one gain crossover, the one at the smallest
-    margin (deviation from gain=0dB), in absolute sense, is
+    margin (deviation from gain = 1), in absolute sense, is
     returned. Likewise the smallest phase margin (in absolute sense)
     is returned.
 

diff --git a/control/modelsimp.py b/control/modelsimp.py
@@ -125,8 +125,8 @@ def modred(sys, ELIM, method='matchdc'):
     Raises
     ------
     ValueError
-        * if `method` is not either ``'matchdc'`` or ``'truncate'``
-        * if eigenvalues of `sys.A` are not all in left half plane
+        - if `method` is not either ``'matchdc'`` or ``'truncate'``
+        - if eigenvalues of `sys.A` are not all in left half plane
           (`sys` must be stable)
 
     Examples

diff --git a/control/robust.py b/control/robust.py
@@ -336,14 +336,16 @@ def mixsyn(g,w1=None,w2=None,w3=None):
     Returns
     -------
     k: synthesized controller; StateSpace object
-    cl: closed system mapping evaluation inputs to evaluation outputs; if p is the augmented plant, with
-        [z] = [p11 p12] [w], then cl is the system from w->z with u=-k*y.  StateSpace object.
+    cl: closed system mapping evaluation inputs to evaluation outputs; if 
+    p is the augmented plant, with
+        [z] = [p11 p12] [w], 
         [y]   [p21   g] [u]
+    then cl is the system from w->z with u=-k*y.  StateSpace object.
 
     info: tuple with entries, in order,
-      gamma: scalar; H-infinity norm of cl
-      rcond: array; estimates of reciprocal condition numbers
-              computed during synthesis.  See hinfsyn for details
+        - gamma: scalar; H-infinity norm of cl
+        - rcond: array; estimates of reciprocal condition numbers
+          computed during synthesis.  See hinfsyn for details
 
     If a weighting w is scalar, it will be replaced by I*w, where I is
     ny-by-ny for w1 and w3, and nu-by-nu for w2.

diff --git a/control/statefbk.py b/control/statefbk.py
@@ -52,6 +52,7 @@
 def place(A, B, p):
     """Place closed loop eigenvalues
     K = place(A, B, p)
+
     Parameters
     ----------
     A : 2-d array

diff --git a/control/statesp.py b/control/statesp.py
@@ -414,7 +414,8 @@ def horner(self, s):
 
     # Method for generating the frequency response of the system
     def freqresp(self, omega):
-        """Evaluate the system's transfer func. at a list of freqs, omega.
+        """
+        Evaluate the system's transfer func. at a list of freqs, omega.
 
         mag, phase, omega = self.freqresp(omega)
 
@@ -427,22 +428,22 @@ def freqresp(self, omega):
 
              G(exp(j*omega*dt)) = mag*exp(j*phase).
 
-        Inputs:
+        Inputs
         ------
-           omega: A list of frequencies in radians/sec at which the system
-                    should be evaluated. The list can be either a python list
-                    or a numpy array and will be sorted before evaluation.
+        omega: A list of frequencies in radians/sec at which the system
+            should be evaluated. The list can be either a python list
+            or a numpy array and will be sorted before evaluation.
 
-        Returns:
+        Returns
         -------
-           mag: The magnitude (absolute value, not dB or log10) of the system
-                frequency response.
+        mag: The magnitude (absolute value, not dB or log10) of the system
+            frequency response.
 
-           phase: The wrapped phase in radians of the system frequency
-                  response.
+        phase: The wrapped phase in radians of the system frequency
+            response.
 
-           omega: The list of sorted frequencies at which the response
-                    was evaluated.
+        omega: The list of sorted frequencies at which the response
+            was evaluated.
 
         """
 

diff --git a/doc-requirements.txt b/doc-requirements.txt
@@ -1,6 +1,4 @@
-numpydoc==0.4
-mock==1.0.1
-# install sphinx from git to get patched version
-# (fixes bug in autosummary where tables do not display)
--e git://github.com/sphinx-doc/sphinx.git@stable#egg=Sphinx-origin_stable
-
+numpy
+scipy
+matplotlib
+numpydoc
diff --git a/doc/Makefile b/doc/Makefile
@@ -1,130 +1,20 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-PAPER         =
+SPHINXPROJ    = PythonControlLibrary
+SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	-rm -rf $(BUILDDIR)/* generated/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PythonControl.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PythonControl.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/PythonControl"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PythonControl"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
+.PHONY: help Makefile
 
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/classes.rst b/doc/classes.rst
@@ -1,8 +1,10 @@
-LTI system classes
-==================
-
+.. _class-ref:
 .. currentmodule:: control
 
+******************
+LTI system classes
+******************
+
 The classes listed below are used to represent models of linear time-invariant
 (LTI) systems.  They are usually created from factory functions such as
 :func:`tf` and :func:`ss`, so the user should normally not need to instantiate
@@ -14,3 +16,4 @@ these directly.
    TransferFunction
    StateSpace
    FRD
+