DOC: small documentation tweaks

murrayrm · murrayrm · commit 0a51c27bd103 · 2018-07-14T12:50:17.000-07:00
diff --git a/control/config.py b/control/config.py
@@ -18,6 +18,8 @@
 def use_matlab_defaults():
     """
     Use MATLAB compatible configuration settings
+
+    The following conventions are used:
         * Bode plots plot gain in dB, phase in degrees, frequency in Hertz
     """
     # Bode plot defaults
@@ -28,7 +30,9 @@ def use_matlab_defaults():
 # Set defaults to match FBS (Astrom and Murray)
 def use_fbs_defaults():
     """
-    Use `Astrom and Murray <http://fbsbook.org>`_ compatible settings
+    Use `Feedback Systems <http://fbsbook.org>`_ (FBS) compatible settings
+
+    The following conventions are used:
         * Bode plots plot gain in powers of ten, phase in degrees,
           frequency in Hertz
     """
diff --git a/control/lti.py b/control/lti.py
@@ -82,9 +82,21 @@ def isctime(self, strict=False):
         return self.dt == 0
 
     def issiso(self):
+        '''Check to see if a system is single input, single output'''
         return self.inputs == 1 and self.outputs == 1
 
     def damp(self):
+        '''Natural frequency, damping ratio of system poles
+
+        Returns
+        -------
+        wn : array
+            Natural frequencies for each system pole
+        zeta : array
+            Damping ratio for each system pole
+        poles : array
+            Array of system poles
+        '''
         poles = self.pole()
 
         if isdtime(self, strict=True):
@@ -102,6 +114,16 @@ def dcgain(self):
 
 # Test to see if a system is SISO
 def issiso(sys, strict=False):
+    """
+    Check to see if a system is single input, single output
+
+    Parameters
+    ----------
+    sys : LTI system
+        System to be checked
+    strict: bool (default = False)
+        If strict is True, do not treat scalars as SISO
+    """
     if isinstance(sys, (int, float, complex, np.number)) and not strict:
         return True
     elif not isinstance(sys, LTI):
diff --git a/control/statesp.py b/control/statesp.py
@@ -1248,7 +1248,7 @@ def tf2ss(*args):
 
 def rss(states=1, outputs=1, inputs=1):
     """
-    Create a stable **continuous** random state space object.
+    Create a stable *continuous* random state space object.
 
     Parameters
     ----------
@@ -1285,7 +1285,7 @@ def rss(states=1, outputs=1, inputs=1):
 
 def drss(states=1, outputs=1, inputs=1):
     """
-    Create a stable **discrete** random state space object.
+    Create a stable *discrete* random state space object.
 
     Parameters
     ----------
diff --git a/doc/README b/doc/README
@@ -1,7 +1,11 @@
 Sphinx Documentation
 --------------------
+This directory contains the user manual for the python-control
+toolbox.  The documentation is built using sphinx.  The master toctree
+document is index.rst.
 
-Note: Sphinx actually runs and imports python code, so broken code, or code not in conf.py sys.path, cannot be documented!
+Note: Sphinx actually runs and imports python code, so broken code, or
+code not in conf.py sys.path, cannot be documented!
 
 1.  Get Sphinx [http://sphinx.pocoo.org/]
     [python setup.py build/install]
@@ -14,7 +18,8 @@ Note: Sphinx actually runs and imports python code, so broken code, or code not
 4.  >> touch *.rst
     >> make html  [or make latex]
 
-Creating/updating manual on sourceforge:
-
-5.  >> rsync -rav _build/html/ user@shell.sourceforge.net:/home/project-web/python-control/htdocs/manual-N.mx/
+Creating/updating manual on readthedocs.org:
 
+5.  Log in to readthedocs.org and go to the 'Admin' menu for
+python-control.  Choose 'Versions' from the sidebar and mark the
+latest release as 'Active'.  Update the default version if needed.
diff --git a/doc/control.rst b/doc/control.rst
@@ -154,3 +154,5 @@ Utility functions and conversions
     timebase
     timebaseEqual
     unwrap
+    use_fbs_defaults
+    use_matlab_defaults
diff --git a/doc/conventions.rst b/doc/conventions.rst
@@ -80,7 +80,7 @@ Discrete time systems
 A discrete time system is created by specifying a nonzero 'timebase', dt.
 The timebase argument can be given when a system is constructed:
 
-* dt = None: no timebase specified
+* dt = None: no timebase specified (default)
 * dt = 0: continuous time system
 * dt > 0: discrete time system with sampling period 'dt'
 * dt = True: discrete time with unspecified sampling period
@@ -90,9 +90,9 @@ explicit representation of discrete time systems.
 
 Systems must have compatible timebases in order to be combined.  A system
 with timebase `None` can be combined with a system having a specified
-timebase, and the result will have the timebase of the latter system.
+timebase; the result will have the timebase of the latter system.
 Similarly, a discrete time system with unspecified sampling time (`dt =
-True`) can be combined with a system having a specified sampling time, and
+True`) can be combined with a system having a specified sampling time;
 the result will be a discrete time system with the sample time of the latter
 system.  For continuous time systems, the :func:`sample_system` function or
 the :meth:`StateSpace.sample` and :meth:`TransferFunction.sample` methods
@@ -110,18 +110,23 @@ argument or using the explicit conversion functions :func:`ss2tf` and
 
 Time series data
 ================
-
-This is a convention for function arguments and return values that
-represent time series: sequences of values that change over time. It
-is used throughout the library, for example in the functions
+A variety of functions in the library return time series data: sequences of
+values that change over time.  A common set of conventions is used for
+returning such data: columns represent different points in time, rows are
+different components (e.g., inputs, outputs or states).  For return
+arguments, an array of times is given as the first returned argument,
+followed by one or more arrays of variable values.  This convention is used
+throughout the library, for example in the functions
 :func:`forced_response`, :func:`step_response`, :func:`impulse_response`,
 and :func:`initial_response`.
 
 .. note::
-    This convention is different from the convention used in the library
-    :mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns
-    is interchanged.  Thus, all 2D values must be transposed when they are
-    used with functions from :mod:`scipy.signal`.
+    The convention used by python-control is different from the convention
+    used in the `scipy.signal
+    <https://docs.scipy.org/doc/scipy/reference/signal.html>`_ library. In
+    Scipy's convention the meaning of rows and columns is interchanged.
+    Thus, all 2D values must be transposed when they are used with functions
+    from `scipy.signal`_.
 
 Types:
 
@@ -181,7 +186,7 @@ conventions.  The currently configurable options allow the units for Bode
 plots to be set as dB for gain, degrees for phase and Hertz for frequency
 (MATLAB conventions) or the gain can be given in magnitude units (powers of
 10), corresponding to the conventions used in `Feedback Systems
-<http://www.cds.caltech.edu/~murray/FBSwiki>`_.
+<http://fbsbook.org>`_ (FBS).
 
 Variables that can be configured, along with their default values:
   * bode_dB (False): Bode plot magnitude plotted in dB (otherwise powers of 10)
@@ -194,6 +199,7 @@ Variables that can be configured, along with their default values:
 Functions that can be used to set standard configurations:
 
 .. autosummary::
-
+    :toctree: generated/
+    
     use_fbs_defaults
     use_matlab_defaults
diff --git a/doc/index.rst b/doc/index.rst
@@ -12,7 +12,8 @@ implements basic operations for analysis and design of feedback control systems.
 - Time response: initial, step, impulse
 - Frequency response: Bode and Nyquist plots
 - Control analysis: stability, reachability, observability, stability margins
-- Control design: eigenvalue placement, linear quadratic regulator
+- Control design: eigenvalue placement, LQR, H2, Hinf
+- Model reduction: balanced realizations, Hankel singular values
 - Estimator design: linear quadratic estimator (Kalman filter)
 
 .. rubric:: Documentation
diff --git a/doc/intro.rst b/doc/intro.rst
@@ -7,36 +7,41 @@ Manual.  This manual contains information on using the python-control
 package, including documentation for all functions in the package and
 examples illustrating their use.
 
-Overview of the Toolbox
+Overview of the toolbox
 =======================
 
 The python-control package is a set of python classes and functions that
 implement common operations for the analysis and design of feedback control
 systems.  The initial goal is to implement all of the functionality required
 to work through the examples in the textbook `Feedback Systems
-<http://www.cds.caltech.edu/~murray/FBSwiki>`_ by Astrom and Murray. A
-MATLAB compatibility package (control.matlab) is available that provides
-many of the common functions corresponding to commands available in the
-MATLAB Control Systems Toolbox.
+<http://fbsbook.org>`_ by Astrom and Murray. A :ref:`matlab-module` is
+available that provides many of the common functions corresponding to
+commands available in the MATLAB Control Systems Toolbox.
 
-Some Differences from MATLAB
+Some differences from MATLAB
 ============================
-The python-control package makes use of NumPy and SciPy.  A list of general
-differences between NumPy and MATLAB can be found `here
+The python-control package makes use of `NumPy <http://www.numpy.org>`_ and
+`SciPy <https://www.scipy.org>`_.  A list of general differences between
+NumPy and MATLAB can be found `here
 <http://www.scipy.org/NumPy_for_Matlab_Users>`_.
 
 In terms of the python-control package more specifically, here are
 some thing to keep in mind:
 
 * You must include commas in vectors.  So [1 2 3] must be [1, 2, 3].
-* Functions that return multiple arguments use tuples
-* You cannot use braces for collections; use tuples instead
+* Functions that return multiple arguments use tuples.  
+* You cannot use braces for collections; use tuples instead.
 
 Installation
 ============
 
-The `python-control` package may be installed using pip, conda or the
-standard distutils/setuptools mechanisms.
+The `python-control` package can be installed using pip, conda or the
+standard distutils/setuptools mechanisms.  The package requires `numpy`_ and
+`scipy`_, and the plotting routines require `matplotlib
+<https://matplotlib.org>`_.  In addition, some routines require the `slycot
+<https://github.com/python-control/Slycot>`_ library in order to implement
+more advanced features (including some MIMO functionality).
+
 
 To install using pip::
 
@@ -54,9 +59,10 @@ correctly by running the command::
   python -c "import slycot"
 
 and verifying that no error message appears.  It may be necessary to install
-`slycot` from source, which requires a working FORTRAN compiler and the
-`lapack` library.  More information on the slycot package can be obtained
-from the `slycot project page <https://github.com/python-control/Slycot>`_.
+`slycot` from source, which requires a working FORTRAN compiler and either
+the `lapack` or `openplas` library.  More information on the slycot package
+can be obtained from the `slycot project page
+<https://github.com/python-control/Slycot>`_.
 
 For users with the Anaconda distribution of Python, the following
 commands can be used::
@@ -67,8 +73,9 @@ commands can be used::
 This installs `slycot` and `python-control` from conda-forge, including the
 `openblas` package.
 
-Alternatively, to use setuptools, first `download the source <https://github.com/python-control/python-control/releases>`_ and unpack
-it.  To install in your home directory, use::
+Alternatively, to use setuptools, first `download the source
+<https://github.com/python-control/python-control/releases>`_ and unpack it.
+To install in your home directory, use::
 
   python setup.py install --user
 
@@ -77,11 +84,7 @@ or to install for all users (on Linux or Mac OS)::
   python setup.py build
   sudo python setup.py install
 
-The package requires `numpy` and `scipy`, and the plotting routines require
-`matplotlib`.  In addition, some routines require the `slycot` module,
-described above.
-
-Getting Started
+Getting started
 ===============
 
 There are two different ways to use the package.  For the default interface
