Add autolink (#452)

* add sphinx autolink

* cleanup docs

* simplify links

* minor cleanup

* add return type

* update requirements.txt

* remove intersphinx

Author: ewu63

doc/advancedFeatures.rst

@@ -27,7 +27,7 @@ To turn the history recording on, use the ``storeHistory`` attribute when invoki
 
 .. code-block:: python
 
-  sol = opt(optProb, sens=sens, storeHistory="<your-history-file-name>.hst", ...)
+  sol = opt(optProb, sens=sens, storeHistory="history_file.hst")
 
 
 Hot start
@@ -75,7 +75,7 @@ To enable this feature, use the ``timeLimit`` option when invoking the optimizer
 
 .. code-block:: python
 
-  sol = opt(optProb, sens=sens, timeLimit=24 * 3600, ...)
+  sol = opt(optProb, sens=sens, timeLimit=24 * 3600)
 
 Note that the attribute takes the maximum wall time *in seconds* as an integer number.
 

doc/api/optimizer.rst

@@ -3,9 +3,5 @@
 Optimizer
 ---------
 
-.. currentmodule:: pyoptsparse.pyOpt_optimizer
-
-.. autoclass:: Optimizer
+.. automodule:: pyoptsparse.pyOpt_optimizer
    :members:
-
-.. autofunction:: pyoptsparse.pyOpt_optimizer.OPT

doc/conf.py

@@ -35,3 +35,9 @@
 
 # bibtex
 bibtex_bibfiles = ["pyoptsparse.bib"]
+
+# autolink
+extensions.extend(["sphinx_codeautolink"])
+codeautolink_concat_default = True
+codeautolink_warn_on_missing_inventory = True
+codeautolink_warn_on_failed_resolve = True

doc/guide.rst

@@ -22,6 +22,7 @@ The optimization class is created using the following call:
 
 .. code-block:: python
 
+  from pyoptsparse import Optimization
   optProb = Optimization("name", objconFun)
 
 The general template of the objective and constraint function is as follows:
@@ -47,7 +48,7 @@ If the Optimization problem is unconstrained, ``funcs`` will contain only the ob
 Design Variables
 ++++++++++++++++
 The simplest way to add a single continuous variable with no bounds (side constraints) and initial value of 0.0 is
-to simply call :meth:`addVar <pyoptsparse.pyOpt_optimization.Optimization.addVar>`:
+to simply call :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addVar`:
 
 .. code-block:: python
 
@@ -77,8 +78,8 @@ The ``scale`` keyword will result in the following:
 The purpose of the scale factor is ensure that design variables of widely different magnitudes can be used in the same optimization.
 It is desirable to have the magnitude of all variables within an order of magnitude or two of each other.
 
-The :meth:`addVarGroup <pyoptsparse.pyOpt_optimization.Optimization.addVarGroup>` call is similar to 
-:meth:`addVar <pyoptsparse.pyOpt_optimization.Optimization.addVar>` except that it adds a group of 1 or more variables.
+The :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addVarGroup` call is similar to
+:meth:`~pyoptsparse.pyOpt_optimization.Optimization.addVar` except that it adds a group of 1 or more variables.
 These variables are then returned as a numpy array within the x-dictionary.
 For example, to add 10 variables with no lower bound, and a scale factor of 0.1:
 
@@ -91,7 +92,7 @@ Constraints
 +++++++++++
 
 The simplest way to add a single constraint with no bounds (i.e., not a very useful constraint!) is
-to use the function :meth:`addCon <pyoptsparse.pyOpt_optimization.Optimization.addCon>`:
+to use the function :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addCon`:
 
 .. code-block:: python
 
@@ -148,7 +149,7 @@ Consider the optimization problem given below::
 
 The ``X``'s denote which parts of the Jacobian have non-zero values.
 pyOptSparse does not determine the sparsity structure of the Jacobian automatically,
-it must be specified by the user during calls to :meth:`addCon <pyoptsparse.pyOpt_optimization.Optimization.addCon>` and :meth:`addConGroup <pyoptsparse.pyOpt_optimization.Optimization.addConGroup>`.
+it must be specified by the user during calls to :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addCon` and :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addConGroup`.
 By way of example, the code that generates the  hypothetical optimization problem is as follows:
 
 .. code-block:: python
@@ -182,6 +183,7 @@ By way of example, the call instead may be as follows:
 
 .. code-block:: python
 
+  from scipy import sparse
   jac = sparse.lil_matrix((3, 3))
   jac[0, 0] = 1.0
   jac[1, 1] = 4.0
@@ -224,7 +226,7 @@ Objectives
 ++++++++++
 
 Each optimization will require at least one objective to be added.
-This is accomplished using a the call to :meth:`addObj <pyoptsparse.pyOpt_optimization.Optimization.addObj>`:
+This is accomplished using a the call to :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addObj`:
 
 .. code-block:: python
 
@@ -262,12 +264,6 @@ For example, if the optimization problem has one objective ``obj``, two constrai
 
   {"obj": {"xvars": [1, 2, 3]}, "con": {"xvars": [[4, 5, 6], [7, 8, 9]]}}
 
-Once this function is constructed, users can pass its function handle to the optimizer when it's called via:
-
-.. code-block:: python
-
-  sol = opt(optProb, sens=sens, ...)
-
 
 Optimizer Instantiation
 +++++++++++++++++++++++
@@ -278,17 +274,40 @@ The first, and most explicit approach is to directly import the optimizer class,
 
   from pyoptsparse import SLSQP
 
-  opt = SLSQP(...)
+  opt = SLSQP(options=options)
 
 However, in order to easily switch between different optimizers without having to import each class, a convenience function called
-:meth:`OPT <pyoptsparse.pyOpt_optimizer.OPT>` is provided.
+:meth:`~pyoptsparse.pyOpt_optimizer.OPT` is provided.
 It accepts a string argument in addition to the usual options, and instantiates the optimizer object based on the string:
 
 .. code-block:: python
 
   from pyoptsparse import OPT
 
-  opt = OPT("SLSQP", ...)
+  opt = OPT("SLSQP", options=options)
 
 Note that the name of the optimizer is case-insensitive, so ``slsqp`` can also be used.
 This makes it easy to for example choose the optimizer from the command-line, or more generally select the optimizer using strings without preemptively importing all classes.
+
+Calling the Optimizer
++++++++++++++++++++++
+
+The optimization is started by invoking the ``__call__`` function of the optimizer object with the optimization problem as an argument.
+For example, to use finite difference, the call would look like:
+
+.. code-block:: python
+
+  sol = opt(optProb, sens="FD")
+
+To provide analytic gradients, the call would look like:
+
+.. code-block:: python
+
+  sol = opt(optProb, sens=sens)
+
+Some of the optimizers also have additional options that can be passed in.
+See the optimizer-specific documentation page for more details.
+
+Postprocessing
+++++++++++++++
+The result of the optimization is returned in a :class:`pyoptsparse.pyOpt_solution.Solution` object.

doc/quickstart.rst

@@ -28,8 +28,8 @@ For the TP37, the objective function is a simple analytic function:
 Notes:
 
 *   The ``xdict`` variable is a dictionary whose keys are the names from each 
-    :meth:`addVar <pyoptsparse.pyOpt_optimization.Optimization.addVar>` and 
-    :meth:`addVarGroup <pyoptsparse.pyOpt_optimization.Optimization.addVarGroup>` call. The line
+    :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addVar` and 
+    :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addVarGroup` call. The line
 
     .. code-block:: python
 
@@ -45,9 +45,9 @@ Notes:
 
     creates a list of length 2, which stores the numerical values of the two constraints.
     The ``funcs`` dictionary return must contain keys that match the constraint names from
-    :meth:`addCon <pyoptsparse.pyOpt_optimization.Optimization.addCon>` and
-    :meth:`addConGroup <pyoptsparse.pyOpt_optimization.Optimization.addConGroup>`
-    as well as the objectives from :meth:`addObj <pyoptsparse.pyOpt_optimization.Optimization.addObj>` calls.
+    :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addCon` and
+    :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addConGroup`
+    as well as the objectives from :meth:`~pyoptsparse.pyOpt_optimization.Optimization.addObj` calls.
     This is done in the following calls:
 
     .. code-block:: python
@@ -87,7 +87,7 @@ This call adds two variables with name ``con``.
 There is no lower bound for the variables and the upper bound is 0.0. 
 
 We must also assign the the key value for the objective using the
-:meth:`addObj <pyoptsparse.pyOpt_optimization.Optimization.addObj>` call:
+:meth:`~pyoptsparse.pyOpt_optimization.Optimization.addObj` call:
 
 .. literalinclude:: ../examples/tp037.py
    :start-after: # rst begin addObj

doc/requirements.txt

@@ -1 +1,2 @@
 sphinx_mdolab_theme>=1.2
+sphinx-codeautolink

pyoptsparse/pyOpt_optimizer.py

@@ -961,10 +961,11 @@ def getInform(self, infocode=None):
 
 # List of optimizers as an enum
 Optimizers = Enum("Optimizers", "SNOPT IPOPT SLSQP NLPQLP CONMIN NSGA2 PSQP ALPSO ParOpt")
+"""Special enum containing all possible optimizers"""
 
 
-def OPT(optName, *args, **kwargs):
-    """
+def OPT(optName, *args, **kwargs) -> Optimizer:
+    r"""
     This is a simple utility function that enables creating an
     optimizer based on the 'optName' string. This can be useful for
     doing optimization studies with respect to optimizer since you
@@ -974,9 +975,9 @@ def OPT(optName, *args, **kwargs):
     ----------
     optName : str or enum
        Either a string identifying the optimizer to create, e.g. "SNOPT", or
-       an enum accessed via ``pyoptsparse.Optimizers``, e.g. ``Optimizers.SNOPT``.
+       an enum accessed via :class:`~pyoptsparse.pyOpt_optimizer.Optimizers`, e.g. ``pyoptsparse.Optimizers.SNOPT``.
 
-    \\*args, \\*\\*kwargs : varies
+    \*args, \*\*kwargs : varies
        Passed to optimizer creation.
 
     Returns