fix module/sub-package references (with developer notes)

Author: murrayrm

control/flatsys/__init__.py

@@ -9,14 +9,14 @@
 trajectories for differentially flat systems.
 
 A differentially flat system is defined by creating an object using the
-`flatsys.FlatSystem` class, which has member functions for mapping the
+`FlatSystem` class, which has member functions for mapping the
 system state and input into and out of flat coordinates.  The
-`flatsys.point_to_point` function can be used to create a trajectory
+`point_to_point` function can be used to create a trajectory
 between two endpoints, written in terms of a set of basis functions defined
-using the `flatsys.BasisFamily` class.  The resulting trajectory is return
-as a `flatsys.SystemTrajectory` object and can be evaluated using the
-`flatsys.SystemTrajectory.eval` member function.  Alternatively, the
-`flatsys.solve_flat_ocp` function can be used to solve an optimal control
+using the `BasisFamily` class.  The resulting trajectory is return
+as a `SystemTrajectory` object and can be evaluated using the
+`SystemTrajectory.eval` member function.  Alternatively, the
+`solve_flat_ocp` function can be used to solve an optimal control
 problem with trajectory and final costs or constraints.
 
 The docstring examples assume that the following import commands::

control/flatsys/basis.py

@@ -1,9 +1,10 @@
 # basis.py - BasisFamily class
 # RMM, 10 Nov 2012
 
-"""The :mod:`control.flatsys.basis` module defines the
-`flatsys.BasisFamily` class that used to specify a set of basis
-functions for implementing differential flatness computations.
+"""Define base class for implementing basis functions.
+
+This module defines the `BasisFamily` class that used to specify a set
+of basis functions for implementing differential flatness computations.
 
 """
 

control/flatsys/bezier.py

@@ -3,9 +3,8 @@
 
 r"""1D Bezier curve basis functions.
 
-The :mod:`control.flatsys.bezier` module defines the
-`BezierFamily` class, which implements a set of basis functions
-based on Bezier curves:
+This module defines the `BezierFamily` class, which implements a set of
+basis functions based on Bezier curves:
 
 .. math:: \phi_i(t) = \sum_{i=0}^n {n \choose i} (T - t)^{n-i} t^i
 

control/flatsys/flatsys.py

@@ -23,11 +23,10 @@
 class FlatSystem(NonlinearIOSystem):
     """Base class for representing a differentially flat system.
 
-    The FlatSystem class is used as a base class to describe
-    differentially flat systems for trajectory generation.  The output
-    of the system does not need to be the differentially flat output.
-    Flat systems are usually created with the `~control.flatsys.flatsys`
-    factory function.
+    The FlatSystem class is used as a base class to describe differentially
+    flat systems for trajectory generation.  The output of the system does
+    not need to be the differentially flat output.  Flat systems are
+    usually created with the `flatsys` factory function.
 
     Parameters
     ----------
@@ -334,12 +333,12 @@ def point_to_point(
 
     Parameters
     ----------
-    sys : FlatSystem object
+    sys : `FlatSystem` object
         Description of the differentially flat system.  This object must
-        define a function `flatsys.forward` that takes the system state and
-        produceds the flag of flat outputs and a system `flatsys.reverse`
-        that takes the flag of the flat output and prodes the state and
-        input.
+        define a function `~FlatSystem.forward` that takes the system state
+        and produces the flag of flat outputs and a function
+        `~FlatSystem.reverse` that takes the flag of the flat output and
+        prodes the state and input.
 
     timepts : float or 1D array_like
         The list of points for evaluating cost and constraints, as well as
@@ -355,9 +354,9 @@ def point_to_point(
         The initial time for the trajectory (corresponding to x0).  If not
         specified, its value is taken to be zero.
 
-    basis : `flatsys.BasisFamily` object, optional
+    basis : `BasisFamily` object, optional
         The basis functions to use for generating the trajectory.  If not
-        specified, the `flatsys.PolyFamily` basis family
+        specified, the `PolyFamily` basis family
         will be used, with the minimal number of elements required to find a
         feasible trajectory (twice the number of system states)
 
@@ -402,9 +401,9 @@ def point_to_point(
 
     Returns
     -------
-    traj : `flatsys.SystemTrajectory` object
+    traj : `SystemTrajectory` object
         The system trajectory is returned as an object that implements the
-        `~flatsys.SystemTrajectory.eval` function, we can be used to
+        `~SystemTrajectory.eval` function, we can be used to
         compute the value of the state and input and a given time t.
 
     Notes
@@ -667,12 +666,12 @@ def solve_flat_ocp(
 
     Parameters
     ----------
-    sys : FlatSystem object
+    sys : `FlatSystem` object
         Description of the differentially flat system.  This object must
-        define a function `flatsys.forward` that takes the system state and
-        produceds the flag of flat outputs and a system `flatsys.reverse`
-        that takes the flag of the flat output and prodes the state and
-        input.
+        define a function `~FlatSystem.forward` that takes the system state
+        and produces the flag of flat outputs and a function
+        `~FlatSystem.reverse` that takes the flag of the flat output and
+        prodes the state and input.
 
     timepts : float or 1D array_like
         The list of points for evaluating cost and constraints, as well as
@@ -684,9 +683,9 @@ def solve_flat_ocp(
         values are given as None, they are replaced by a vector of zeros of
         the appropriate dimension.
 
-    basis : `flatsys.BasisFamily` object, optional
+    basis : `BasisFamily` object, optional
         The basis functions to use for generating the trajectory.  If not
-        specified, the `flatsys.PolyFamily` basis family
+        specified, the `PolyFamily` basis family
         will be used, with the minimal number of elements required to find a
         feasible trajectory (twice the number of system states)
 
@@ -735,22 +734,22 @@ def solve_flat_ocp(
 
     Returns
     -------
-    traj : `flatsys.SystemTrajectory` object
+    traj : `SystemTrajectory`
         The system trajectory is returned as an object that implements the
-        `~flatsys.SystemTrajectory.eval` function, we can be used to
-        compute the value of the state and input and a given time t.
+        `SystemTrajectory.eval` function, we can be used to
+        compute the value of the state and input and a given time `t`.
 
     Notes
     -----
     Additional keyword parameters can be used to fine tune the behavior of
     the underlying optimization function.  See `minimize_*` keywords in
-    `optimal.OptimalControlProblem` for more information.
+    `control.optimal.OptimalControlProblem` for more information.
 
     The return data structure includes the following additional attributes:
 
-        * success : bool indicating whether the optimization succeeded
-        * cost : computed cost of the returned trajectory
-        * message : message returned by optimization if success if False
+        * `success` : bool indicating whether the optimization succeeded
+        * `cost` : computed cost of the returned trajectory
+        * `message` : message returned by optimization if success if False
 
     A common failure in solving optimal control problem is that the default
     initial guess violates the constraints and the optimizer can't find a

control/flatsys/linflat.py

@@ -84,7 +84,7 @@ def __init__(self, linsys, **kwargs):
     def forward(self, x, u, params):
         """Compute the flat flag given the states and input.
 
-        See `control.flatsys.FlatSystem.forward` for more info.
+        See `FlatSystem.forward` for more info.
 
         """
         x = np.reshape(x, (-1, 1))
@@ -101,7 +101,7 @@ def forward(self, x, u, params):
     def reverse(self, zflag, params):
         """Compute the states and input given the flat flag.
 
-        See `control.flatsys.FlatSystem.reverse` for more info.
+        See `FlatSystem.reverse` for more info.
 
         """
         z = zflag[0][0:-1]

control/flatsys/systraj.py

@@ -18,7 +18,7 @@ class SystemTrajectory:
 
     The `SystemTrajectory` class is used to represent the
     trajectory of a (differentially flat) system.  Used by the
-    `trajsys.point_to_point` function to return a trajectory.
+    `point_to_point` function to return a trajectory.
 
     Parameters
     ----------
@@ -131,7 +131,7 @@ def response(self, tlist, transpose=False, return_x=False, squeeze=None):
 
         Returns
         -------
-        results : TimeResponseData
+        results : `control.TimeResponseData`
             Time response represented as a `TimeResponseData` object
             containing the following properties:
 

control/matlab/__init__.py

@@ -4,11 +4,11 @@
 
 """MATLAB compatibility sub-package.
 
-The :mod:`control.matlab` sub-package contains a number of functions
-that emulate some of the functionality of MATLAB.  The intent of these
-functions is to provide a simple interface to the python control
-systems library (python-control) for people who are familiar with the
-MATLAB Control Systems Toolbox (tm).
+This sub-package contains a number of functions that emulate some of
+the functionality of MATLAB.  The intent of these functions is to
+provide a simple interface to the python control systems library
+(python-control) for people who are familiar with the MATLAB Control
+Systems Toolbox (tm).
 
 """
 

control/optimal.py

@@ -6,7 +6,14 @@
 """Optimization-based control module.
 
 This module provides support for optimization-based controllers for
-nonlinear systems with state and input constraints.
+nonlinear systems with state and input constraints.  An optimal
+control problem can be solved using the `solve_ocp` function or set up
+using the `OptimalControlProblem` class and then solved using the
+`~OptimalControlProblem.compute_trajectory` method.  Utility functions
+are available to define common cost functions and input/state
+constraints.  Optimal estimation problems can be solved using the
+`solve_oep` function or by using the `OptimalEstimationProblem` class
+and the `~OptimalEstimationProblem.compute_estimate` method..
 
 The docstring examples assume the following import commands::
 
@@ -49,7 +56,7 @@ class OptimalControlProblem():
     to specify an optimal control problem: the system dynamics, cost
     function, and constraints.  As much as possible, the information used
     to specify an optimal control problem matches the notation and
-    terminology of the SciPy `optimize.minimize` module, with the hope that
+    terminology of `scipy.optimize` module, with the hope that
     this makes it easier to remember how to describe a problem.
 
     Parameters
@@ -1190,7 +1197,7 @@ def create_mpc_iosystem(
 
     constraints : list of tuples, optional
         List of constraints that should hold at each point in the time
-        vector.  See `optimal.solve_ocp` for more details.
+        vector.  See `solve_ocp` for more details.
 
     terminal_cost : callable, optional
         Function that returns the terminal cost given the final state
@@ -1201,8 +1208,8 @@ def create_mpc_iosystem(
         Same format as `constraints`.
 
     **kwargs
-        Additional parameters, passed to `scipy.optimal.minimize` and
-        `NonlinearIOSystem`.
+        Additional parameters, passed to `scipy.optimize.minimize` and
+        `~control.NonlinearIOSystem`.
 
     Returns
     -------
@@ -2021,11 +2028,11 @@ def solve_oep(
     control_indices : int, slice, or list of int or string, optional
         Specify the indices in the system input vector that correspond to
         the control inputs.  For more information on possible values, see
-        `optimal.OptimalEstimationProblem`.
+        `OptimalEstimationProblem`.
     disturbance_indices : int, list of int, or slice, optional
         Specify the indices in the system input vector that correspond to
         the input disturbances.  For more information on possible values, see
-        `optimal.OptimalEstimationProblem`.
+        `OptimalEstimationProblem`.
     initial_guess : 2D array_like, optional
         Initial guess for the state estimate at each time point.
     print_summary : bool, optional
@@ -2061,7 +2068,7 @@ def solve_oep(
     -----
     Additional keyword parameters can be used to fine-tune the behavior of
     the underlying optimization and integration functions.  See
-    `optimal.OptimalControlProblem` for more information.
+    `OptimalControlProblem` for more information.
 
     """
     # Set up the optimal control problem

control/phaseplot.py

@@ -7,9 +7,10 @@
 """Generate 2D phase portraits.
 
 This module contains functions for generating 2D phase plots. The base
-function for creating phase plane portraits is `phase_plane_plot`,
+function for creating phase plane portraits is `~control.phase_plane_plot`,
 which generates a phase plane portrait for a 2 state I/O system (with no
-inputs).
+inputs). Utility functions are available to customize the individual
+elements of a phase plane portrait.
 
 The docstring examples assume the following import commands::
 
@@ -85,8 +86,9 @@ def phase_plane_plot(
         a dict of parameters and values. For a callable, `params` should be
         dict with key 'args' and value given by a tuple (passed to callable).
     color : matplotlib color spec, optional
-        Plot all elements in the given color (use `plot_<fcn>` = {'color': c}
-        to set the color in one element of the phase plot.
+        Plot all elements in the given color (use ``plot_<element>`` =
+        {'color': c} to set the color in one element of the phase
+        plot (equilpoints, separatrices, streamlines, etc).
     ax : matplotlib.axes.Axes, optional
         The matplotlib axes to draw the figure on.  If not specified and
         the current figure has a single axes, that axes is used.
@@ -130,7 +132,7 @@ def phase_plane_plot(
     plot_streamlines : bool or dict, optional
         If True (default) then plot streamlines based on the pointdata
         and gridtype.  If set to a dict, pass on the key-value pairs in
-        the dict as keywords to `phaseplot.streamlines`.
+        the dict as keywords to `streamlines`.
     plot_vectorfield : bool or dict, optional
         If True (default) then plot the vector field based on the pointdata
         and gridtype.  If set to a dict, pass on the key-value pairs in

doc/develop.rst

@@ -450,6 +450,42 @@ The reference manual should provide a fairly comprehensive description
 of every class, function and configuration variable in the package.
 
 
+Modules and sub-packages
+------------------------
+
+When documenting (independent) modules and sub-packages (refered to
+here collectively as modules), use the following guidelines for
+documentatation:
+
+* In module docstrings, refer to module functions and classes without
+  including the module prefix.  This will let Sphinx set up the links
+  to the functions in the proper way and has the advantage that it
+  keeps the docstrings shorter.
+
+* Objects in the parent (`control`) package should be referenced using
+  the `~control` prefix, so that Sphinx generates the links properly
+  (otherwise it looks within the package).
+
+* In the User Guide, set ``currentmodule`` to ``control`` and refer to
+  the module objects using the prefix `~prefix` in the text portions
+  of the document but `px` (shortened prefix) in the code sections.
+  This will let users copy and past code from the examples and is
+  consistent with the use of the `ct` short prefix.  Since this is in
+  the User Guide, the additional characters are not as big an issue.
+
+* If you include an `autosummary` of functions in the User Guide
+  section, list the functions using the regular prefix (without ``~``)
+  to remind everyone the function is in a module.
+
+* When referring to a module function or class in a docstring or User
+  Guide section that is not part of the module, use the fully
+  qualified function or class (\'prefix.function\').
+
+The main overarching principle should be to make sure that references
+to objects that have more detailed information should show up as a
+link, not as code.
+
+
 Utility Functions
 =================