Merge pull request python-control#828 from murrayrm/numpydoc-28Dec2022

murrayrm · web-flow · commit 508dc7ffde6e · 2022-12-29T19:05:27.000-08:00
update docs to use use numpydoc + linkcode
diff --git a/control/descfcn.py b/control/descfcn.py
@@ -236,8 +236,8 @@ def describing_function_plot(
         given by the first value of the tuple and frequency given by the
         second value.
 
-    Example
-    -------
+    Examples
+    --------
     >>> H_simple = ct.tf([8], [1, 2, 2, 1])
     >>> F_saturation = ct.descfcn.saturation_nonlinearity(1)
     >>> amp = np.linspace(1, 4, 10)
diff --git a/control/freqplot.py b/control/freqplot.py
@@ -589,8 +589,8 @@ def nyquist_plot(
         if `return_contour` is Tue.  To obtain the Nyquist curve values,
         evaluate system(s) along contour.
 
-    Additional Parameters
-    ---------------------
+    Other Parameters
+    ----------------
     arrows : int or 1D/2D array of floats, optional
         Specify the number of arrows to plot on the Nyquist curve.  If an
         integer is passed. that number of equally spaced arrows will be
diff --git a/control/iosys.py b/control/iosys.py
@@ -1618,6 +1618,10 @@ def input_output_response(
         number of states in the system, the initial condition will be padded
         with zeros.
 
+    t_eval : array-list, optional
+        List of times at which the time response should be computed.
+        Defaults to ``T``.
+
     return_x : bool, optional
         If True, return the state vector when assigning to a tuple (default =
         False).  See :func:`forced_response` for more details.
@@ -2725,8 +2729,8 @@ def interconnect(syslist, connections=None, inplist=None, outlist=None,
         generated and if `True` then warnings are always generated.
 
 
-    Example
-    -------
+    Examples
+    --------
     >>> P = control.LinearIOSystem(
     >>>        control.rss(2, 2, 2, strictly_proper=True), name='P')
     >>> C = control.LinearIOSystem(control.rss(2, 2, 2), name='C')
@@ -2926,8 +2930,8 @@ def summing_junction(
         Linear input/output system object with no states and only a direct
         term that implements the summing junction.
 
-    Example
-    -------
+    Examples
+    --------
     >>> P = control.tf2io(ct.tf(1, [1, 0]), inputs='u', outputs='y')
     >>> C = control.tf2io(ct.tf(10, [1, 1]), inputs='e', outputs='u')
     >>> sumblk = control.summing_junction(inputs=['r', '-y'], output='e')
diff --git a/control/lti.py b/control/lti.py
@@ -304,8 +304,12 @@ def damp(sys, doprint=True):
     poles: array
         Pole locations
 
-    Algorithm
-    ---------
+    See Also
+    --------
+    pole
+
+    Notes
+    -----
     If the system is continuous,
         wn = abs(poles)
         Z  = -real(poles)/poles.
@@ -320,9 +324,6 @@ def damp(sys, doprint=True):
         wn = abs(s)
         Z = -real(s)/wn.
 
-    See Also
-    --------
-    pole
     """
     wn, damping, poles = sys.damp()
     if doprint:
diff --git a/control/sisotool.py b/control/sisotool.py
@@ -285,7 +285,7 @@ def rootlocus_pid_designer(plant, gain='P', sign=+1, input_signal='r',
         Whether to create Sisotool interactive plot.
 
     Returns
-    ----------
+    -------
     closedloop : class:`StateSpace` system
         The closed-loop system using initial gains.
 
diff --git a/control/statefbk.py b/control/statefbk.py
@@ -126,10 +126,6 @@ def place(A, B, p):
     --------
     place_varga, acker
 
-    Notes
-    -----
-    The return type for 2D arrays depends on the default class set for
-    state space operations.  See :func:`~control.use_numpy_matrix`.
     """
     from scipy.signal import place_poles
 
diff --git a/doc/Makefile b/doc/Makefile
@@ -20,5 +20,5 @@ classes.pdf: classes.fig;	fig2dev -Lpdf $< $@
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-html pdf: Makefile $(FIGS)
+html pdf clean: Makefile $(FIGS)
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/conf.py b/doc/conf.py
@@ -30,7 +30,7 @@
 # -- Project information -----------------------------------------------------
 
 project = u'Python Control Systems Library'
-copyright = u'2020, python-control.org'
+copyright = u'2022, python-control.org'
 author = u'Python Control Developers'
 
 # Version information - read from the source code
@@ -56,7 +56,7 @@
 extensions = [
     'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx', 'sphinx.ext.imgmath',
-    'sphinx.ext.autosummary', 'nbsphinx',
+    'sphinx.ext.autosummary', 'nbsphinx', 'numpydoc', 'sphinx.ext.linkcode'
 ]
 
 # scan documents for autosummary directives and generate stub pages for each.
@@ -139,6 +139,80 @@
 #
 # html_sidebars = {}
 
+# -----------------------------------------------------------------------------
+# Source code links (from numpy)
+# -----------------------------------------------------------------------------
+
+import inspect
+from os.path import relpath, dirname
+
+def linkcode_resolve(domain, info):
+    """
+    Determine the URL corresponding to Python object
+    """
+    if domain != 'py':
+        return None
+
+    modname = info['module']
+    fullname = info['fullname']
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split('.'):
+        try:
+            obj = getattr(obj, part)
+        except Exception:
+            return None
+
+    # strip decorators, which would resolve to the source of the decorator
+    # possibly an upstream bug in getsourcefile, bpo-1764286
+    try:
+        unwrap = inspect.unwrap
+    except AttributeError:
+        pass
+    else:
+        obj = unwrap(obj)
+
+    # Get the filename for the function
+    try:
+        fn = inspect.getsourcefile(obj)
+    except Exception:
+        fn = None
+    if not fn:
+        return None
+
+    # Ignore re-exports as their source files are not within the numpy repo
+    module = inspect.getmodule(obj)
+    if module is not None and not module.__name__.startswith("control"):
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except Exception:
+        lineno = None
+
+    fn = relpath(fn, start=dirname(control.__file__))
+
+    if lineno:
+        linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
+    else:
+        linespec = ""
+
+    base_url = "https://github.com/python-control/python-control/blob/"
+    if 'dev' in control.__version__ or 'post' in control.__version__:
+        return base_url + "main/control/%s%s" % (fn, linespec)
+    else:
+        return base_url + "%s/control/%s%s" % (
+           control.__version__, fn, linespec)
+
+# Don't automaticall show all members of class in Methods & Attributes section
+numpydoc_show_class_members = False
+
+# Don't create a Sphinx TOC for the lists of class methods and attributes
+numpydoc_class_members_toctree = False
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
