updated documentation for 0.6c release

murrayrm · murrayrm · commit cecc8d1c9837 · 2012-11-03T22:51:28.000Z
diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,16 @@
+2012-11-03  Richard Murray  <murray@altura.local>
+
+	* doc/modules.rst: updated documentation format so that items are
+	broken down by functionality and not internal module name.  Still
+	not complete, but most functions should now show up in documentation.
+
+	* doc/index.rst: got rid of todos from documentation (not formatted
+	correctly and shouldn't show up in user documentation)
+
+	* src/lti.py: added missing docstrings
+
+	* doc/intro.rst: small tweaks to text, including adding a link to FBS
+
 2012-11-03  Richard Murray  <murray@altura.local>
 
 	* src/rlocus.py (_RLSortRoots): convert output of range() to
diff --git a/doc/analysis.rst b/doc/analysis.rst
@@ -1,2 +1,22 @@
 Control System Analysis
-***********************
+***********************
+
+.. autofunction:: control.acker
+.. autofunction:: control.ctrb
+.. autofunction:: control.care
+.. autofunction:: control.dare
+.. autofunction:: control.dlyap
+.. autofunction:: control.dcgain
+.. autofunction:: control.evalfr
+.. autofunction:: control.gram
+.. autofunction:: control.lyap
+.. autofunction:: control.freqresp
+.. autofunction:: control.margin
+.. autofunction:: control.markov
+.. autofunction:: control.obsv
+.. autofunction:: control.phase_crossover_frequencies
+.. autofunction:: control.pole
+.. autofunction:: control.root_locus
+.. autofunction:: control.stability_margins
+.. autofunction:: control.zero
+
diff --git a/doc/bdalg_strings.rst b/doc/bdalg_strings.rst
@@ -3,5 +3,7 @@ Block Diagram Algebra
 
 .. toctree::
 
-.. automodule:: bdalg
-   :members:
+.. autofunction:: control.feedback
+.. autofunction:: control.negate
+.. autofunction:: control.parallel
+.. autofunction:: control.series
diff --git a/doc/class_strings.rst b/doc/class_strings.rst
@@ -1,6 +1,11 @@
 Python-Control Classes
 ********************** 
 
+LTI System Class
+================
+.. automodule:: lti
+   :members:
+
 State Space Class
 =================
 .. automodule:: statesp
diff --git a/doc/freqplot.rst b/doc/freqplot.rst
@@ -5,10 +5,10 @@ Frequency Domain Plotting
 
 Plotting routines
 =================
-.. autofunction:: freqplot.bode_plot
-.. autofunction:: freqplot.nyquist_plot
-.. autofunction:: freqplot.gangof4_plot
-.. autofunction:: nichols.nichols_plot
+.. autofunction:: control.bode_plot
+.. autofunction:: control.nyquist_plot
+.. autofunction:: control.gangof4_plot
+.. autofunction:: control.nichols_plot
 
 Utility functions
 =================
diff --git a/doc/index.rst b/doc/index.rst
@@ -17,17 +17,13 @@ Contents:
    :maxdepth: 2
    
    intro
-   class_strings
    modules
+   class_strings
+   matlab_strings
    examples
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
-
-----------------------------------
-
-.. todolist::
diff --git a/doc/intro.rst b/doc/intro.rst
@@ -10,14 +10,14 @@ examples illustrating their use.
 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 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.
+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.
 
 In addition to the documentation here, there is a project wiki that
 contains some additional information about how to use the package
@@ -37,10 +37,9 @@ 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
-* Can't use braces for collections; use tuples instead
-* Transfer functions are only implemented for SISO systems (due to
-  limitations in the underlying signals.lti class); use state space
-  representations for MIMO systems.
+* You cannot use braces for collections; use tuples instead
+* Transfer functions are currently only implemented for SISO systems; use
+  state space representations for MIMO systems.
 
 Getting Started
 ---------------
@@ -52,15 +51,16 @@ Getting Started
 3. To see if things are working correctly, run ipython -pylab and run
    the script 'examples/secord-matlab.py'.  This should generate a
    step response, Bode plot and Nyquist plot for a simple second order
-   system.
+   system.  (For more detailed tests, run nosetests in the main directory.)
 
 4. To see the commands that are available, run the following commands in
    ipython::
 
        >>> import control
-       >>> ?control.matlab
+       >>> ?control
 
 5. If you want to have a MATLAB-like environment for running the control
    toolbox, use::
 
        >>> from control.matlab import *
+       >>> ?control.matlab
diff --git a/doc/modsimp_strings.rst b/doc/modsimp_strings.rst
@@ -1,5 +1,6 @@
 Model Simplification Tools
 **************************
 
-.. automodule:: modelsimp
-    :members:
+.. autofunction:: control.balred
+.. autofunction:: control.hsvd
+.. autofunction:: control.modred
diff --git a/doc/modules.rst b/doc/modules.rst
@@ -1,12 +1,13 @@
-Python-Control Modules
-**********************
+Python-Control Functions
+************************
 
 .. toctree::
 
+   creation
    bdalg_strings
    analysis
    freqplot
    timeresp
    synthesis
    modsimp_strings
-   matlab_strings
+   utilities
diff --git a/doc/synthesis.rst b/doc/synthesis.rst
@@ -1,2 +1,5 @@
 Control System Synthesis
-************************
+************************
+
+.. autofunction:: control.lqr
+.. autofunction:: control.place
diff --git a/doc/timeresp.rst b/doc/timeresp.rst
@@ -1,8 +1,13 @@
 Time Domain Simulation
 **********************
 
-.. automodule:: timeresp
-    :members:
+Time responses
+==============
+.. autofunction:: control.forced_response
+.. autofunction:: control.initial_response
+.. autofunction:: control.step_response
 
+Phase portraits
+===============
 .. autofunction:: phaseplot.phase_plot
 .. autofunction:: phaseplot.box_grid
diff --git a/doc/utilities.rst b/doc/utilities.rst
@@ -0,0 +1,4 @@
+Utility Functions
+*****************
+
+.. autofunction:: control.unwrap
diff --git a/src/bdalg.py b/src/bdalg.py
@@ -204,7 +204,7 @@ def feedback(sys1, sys2, sign=-1):
     parallel
 
     Notes
-    ----
+    -----
     This function is a wrapper for the feedback function in the StateSpace and
     TransferFunction classes.  It calls TransferFunction.feedback if `sys1` is a
     TransferFunction object, and StateSpace.feedback if `sys1` is a StateSpace
diff --git a/src/lti.py b/src/lti.py
@@ -1,7 +1,7 @@
 """lti.py
 
-The lti module contains the Lti parent class to the child classes StateSpace and
-TransferFunction.  It is designed for use in the python-control library.
+The Lti module contains the Lti parent class to the child classes StateSpace
+and TransferFunction.  It is designed for use in the python-control library.
 
 Routines in this module:
 
@@ -13,7 +13,6 @@
 """
 
 class Lti:
-
     """Lti is a parent class to linear time invariant control (LTI) objects.
     
     Lti is the parent to the StateSpace and TransferFunction child
@@ -90,7 +89,16 @@ def timebase(sys, strict=True):
 
 # Check to see if two timebases are equal
 def timebaseEqual(sys1, sys2):
-    # TODO: add docstring
+    """Check to see if two systems have the same timebase
+
+    timebaseEqual(sys1, sys2)
+
+    returns True if the timebases for the two systems are compatible.  By
+    default, systems with timebase 'None' are compatible with either
+    discrete or continuous timebase systems.  If two systems have a discrete
+    timebase (dt > 0) then their timebases must be equal.
+    """
+
     if (type(sys1.dt) == bool or type(sys2.dt) == bool):
         # Make sure both are unspecified discrete timebases
         return type(sys1.dt) == type(sys2.dt) and sys1.dt == sys2.dt
@@ -102,7 +110,17 @@ def timebaseEqual(sys1, sys2):
 
 # Check to see if a system is a discrete time system
 def isdtime(sys, strict=False):
-    # TODO: add docstring
+    """
+    Check to see if a system is a discrete time system
+
+    Parameters
+    ----------
+    sys : LTI system
+        System to be checked
+    strict: bool (default = False)
+        If strict is True, make sure that timebase is not None
+    """
+
     # Check to see if this is a constant
     if isinstance(sys, (int, float, complex)):
         # OK as long as strict checking is off
@@ -122,7 +140,17 @@ def isdtime(sys, strict=False):
 
 # Check to see if a system is a continuous time system
 def isctime(sys, strict=False):
-    # TODO: add docstring
+    """
+    Check to see if a system is a continuous time system
+
+    Parameters
+    ----------
+    sys : LTI system
+        System to be checked
+    strict: bool (default = False)
+        If strict is True, make sure that timebase is not None
+    """
+
     # Check to see if this is a constant
     if isinstance(sys, (int, float, complex)):
         # OK as long as strict checking is off
diff --git a/src/statesp.py b/src/statesp.py
@@ -1,11 +1,10 @@
-# -*- coding: utf-8 -*-
-"""stateSpace.py
+"""statesp.py
 
 State space representation and functions.
 
-This file contains the StateSpace class, which is used to represent
-linear systems in state space.  This is the primary representation
-for the python-control library.
+This file contains the StateSpace class, which is used to represent linear
+systems in state space.  This is the primary representation for the
+python-control library.
 
 Routines in this module:
 
@@ -73,7 +72,6 @@
 Revised: Kevin K. Chen, Dec 10
 
 $Id$
-
 """
 
 from numpy import all, angle, any, array, asarray, concatenate, cos, delete, \
@@ -88,7 +86,6 @@
 from control.lti import Lti, timebaseEqual, isdtime
 
 class StateSpace(Lti):
-
     """The StateSpace class represents state space instances and functions.
     
     The StateSpace class is used throughout the python-control library to
