Add docs for scico.solver module

docs/source/conf.py

@@ -395,14 +395,24 @@ class ExperimentAnalysis:
 
 snp_func = getmembers(scico.numpy, isfunction)
 for _, f in snp_func:
-    if f.__module__[0:14] == "jax._src.numpy" or f.__module__ == "scico.numpy._create":
+    if (
+        f.__module__ == "scico.numpy"
+        or f.__module__[0:14] == "jax._src.numpy"
+        or f.__module__ == "scico.numpy._create"
+    ):
         # Rewrite module name so that function is included in docs
         f.__module__ = "scico.numpy"
         # Attempt to fix incorrect cross-reference
         if f.__name__ == "compare_chararrays":
             modname = "numpy.char"
         else:
             modname = "numpy"
+        f.__doc__ = re.sub(
+            r"^:func:`([\w_]+)` wrapped to operate",
+            r":obj:`jax.numpy.\1` wrapped to operate",
+            str(f.__doc__),
+            flags=re.M,
+        )
         f.__doc__ = re.sub(
             r"^LAX-backend implementation of :func:`([\w_]+)`.",
             r"LAX-backend implementation of :obj:`%s.\1`." % modname,
@@ -429,6 +439,40 @@ class ExperimentAnalysis:
 scico.numpy.vectorize.__doc__ = re.sub("^  ", "", scico.numpy.vectorize.__doc__, flags=re.M)
 
 
+# Similar processing for scico.scipy
+import scico.scipy
+
+ssp_func = getmembers(scico.scipy.special, isfunction)
+for _, f in ssp_func:
+    if f.__module__[0:11] == "scico.scipy" or f.__module__[0:14] == "jax._src.scipy":
+        # Attempt to fix incorrect cross-reference
+        f.__doc__ = re.sub(
+            r"^:func:`([\w_]+)` wrapped to operate",
+            r":obj:`jax.scipy.special.\1` wrapped to operate",
+            str(f.__doc__),
+            flags=re.M,
+        )
+        modname = "scipy.special"
+        f.__doc__ = re.sub(
+            r"^LAX-backend implementation of :func:`([\w_]+)`.",
+            r"LAX-backend implementation of :obj:`%s.\1`." % modname,
+            str(f.__doc__),
+            flags=re.M,
+        )
+        # Remove cross-reference to numpydoc style references section
+        f.__doc__ = re.sub(r" \[(\d+)\]_", "", f.__doc__, flags=re.M)
+        # Remove entire numpydoc references section
+        f.__doc__ = re.sub(r"References\n----------\n.*\n", "", f.__doc__, flags=re.DOTALL)
+        # Remove problematic citation
+        f.__doc__ = re.sub("See \[dlmf\]_ for details.", "", f.__doc__, re.M)
+        f.__doc__ = re.sub("\[dlmf\]_", "NIST DLMF", f.__doc__, re.M)
+
+# Fix indentation problems
+scico.scipy.special.sph_harm.__doc__ = re.sub(
+    "^Computes the", "  Computes the", scico.scipy.special.sph_harm.__doc__, flags=re.M
+)
+
+
 def class_inherit_diagrams(_):
     # Insert inheritance diagrams for classes that have base classes
     import scico

docs/source/style.rst

@@ -118,7 +118,7 @@ We follow the `Google string conventions <https://google.github.io/styleguide/py
 Imports
 -------
 
-We follow the `Google import conventions <https://google.github.io/styleguide/pyguide.html#22-imports>`_. The usage of ``import`` statements should be reserved for packages and modules only excluding individual classes and functions. The only exception to this is the typing module.
+We follow the `Google import conventions <https://google.github.io/styleguide/pyguide.html#22-imports>`_. The use of ``import`` statements should be reserved for packages and modules only, i.e. individual classes and functions should not be imported. The only exception to this is the typing module.
 
 -  Use ``import x`` for importing packages and modules, where x is the package or module name.
 -  Use ``from x import y`` where x is the package name and y is the module name.
@@ -135,7 +135,7 @@ We follow the `Google variable typing conventions <https://google.github.io/styl
 
    .. code-block:: python
 
-      a : Foo = SomeDecoratedFunction()
+      a: Foo = SomeDecoratedFunction()
 
 - Avoid global variables.
 - A function can refer to variables defined in enclosing functions but cannot assign to them.
@@ -296,7 +296,7 @@ We follow the `Google class conventions <https://google.github.io/styleguide/pyg
 .. code:: Python
 
     class foo:
-        """One liner describing the class.
+	"""One-liner describing the class.
 
         Additional information or description for the class.
         Can be multi-line
@@ -424,18 +424,18 @@ If a comment consists of one or more full sentences (as is typically the case fo
 Markup
 ~~~~~~
 
-The following components require the recommended markup taken from `NumPy's Conventions <https://numpydoc.readthedocs.io/en/latest/format.html#common-rest-concepts>`_.:
+The following components require the recommended markup taken from the `NumPy Conventions <https://numpydoc.readthedocs.io/en/latest/format.html#common-rest-concepts>`__.:
 
 - Paragraphs:
   Indentation is significant and indicates the indentation of the output. New paragraphs are marked with a blank line.
-- Variable, module, function, and class names:
-  Should be written in between single back-ticks (`x`).
+- Variable, parameter, module, function, method, and class names:
+  Should be written between single back-ticks (e.g. \`x\`, rendered as `x`), but note that use of `Sphinx cross-reference syntax <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects>`_ is preferred for modules (`:mod:\`module-name\`` ), functions (`:func:\`function-name\`` ), methods (`:meth:\`method-name\`` ) and classes (`:class:\`class-name\`` ).
 - None, NoneType, True, and False:
-  Should be written in between double back-ticks (``None``, ``True``).
+  Should be written between double back-ticks (e.g. \`\`None\`\`, \`\`True\`\`, rendered as ``None``, ``True``).
 - Types:
-  Should be written in between double back-ticks (``int``).
+  Should be written between double back-ticks (e.g. \`\`int\`\`, rendered as ``int``).
 
-Other components can use *italics*, **bold**, and ``monospace`` if needed, but not for variable names, doctest code, or multi-line code.
+Other components can use \*italics\*, \*\*bold\*\*, and \`\`monospace\`\` (respectively rendered as *italics*, **bold**, and ``monospace``) if needed, but not for variable names, doctest code, or multi-line code.
 
 
 Documentation
@@ -463,6 +463,8 @@ A few notable guidelines:
     * Avoid capitalization in text except where absolutely necessary,
       e.g., "Newton’s first law."
 
+    * Use a single space after the period at the end of a sentence.
+
 
 The source code (`.rst` files) for these pages does not have a line-length guideline,
 but line breaks at or before 79 characters are encouraged.

scico/array.py

@@ -21,7 +21,7 @@
 
 import scico.blockarray
 import scico.numpy as snp
-from scico.typing import ArrayIndex, Axes, AxisIndex, JaxArray, Shape
+from scico.typing import ArrayIndex, Axes, AxisIndex, DType, JaxArray, Shape
 
 
 def ensure_on_device(
@@ -74,8 +74,8 @@ def ensure_on_device(
 
 
 def no_nan_divide(
-    x: Union[BlockArray, JaxArray], y: Union[BlockArray, JaxArray]
-) -> Union[BlockArray, JaxArray]:
+    x: Union[scico.blockarray.BlockArray, JaxArray], y: Union[scico.blockarray.BlockArray, JaxArray]
+) -> Union[scico.blockarray.BlockArray, JaxArray]:
     """Return `x/y`, with 0 instead of NaN where `y` is 0.
 
     Args:

scico/blockarray.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SPORCO package. Details of the copyright
 # and user license can be found in the 'LICENSE.txt' file distributed

scico/data/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2021 by SCICO Developers
+# Copyright (C) 2021-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/examples.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2021 by SCICO Developers
+# Copyright (C) 2021-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/flax.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/functional/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2021 by SCICO Developers
+# Copyright (C) 2021-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/functional/_flax.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2021 by SCICO Developers
+# Copyright (C) 2021-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the
@@ -17,8 +17,6 @@
 
 PyTree = Any
 
-__author__ = """Cristina Garcia-Cardona <[email protected]>"""
-
 
 class FlaxMap(Functional):
     r"""Functional whose prox applies a trained flax model."""

scico/functional/_functional.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the
@@ -16,10 +16,6 @@
 from scico.blockarray import BlockArray
 from scico.typing import JaxArray
 
-__author__ = """\n""".join(
-    ["Luke Pfister <[email protected]>", "Thilo Balke <[email protected]>"]
-)
-
 
 class Functional:
     r"""Base class for functionals.

scico/functional/_indicator.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the
@@ -18,8 +18,6 @@
 
 from ._functional import Functional
 
-__author__ = """Luke Pfister <[email protected]>"""
-
 
 class NonNegativeIndicator(Functional):
     r"""Indicator function for non-negative orthant.
@@ -50,17 +48,17 @@ def prox(
         self, v: Union[JaxArray, BlockArray], lam: float = 1.0, **kwargs
     ) -> Union[JaxArray, BlockArray]:
         r"""Evaluate the scaled proximal operator of the indicator over
-            the non-negative orthant, :math:`I_{>= 0} `,:
+        the non-negative orthant, :math:`I_{>= 0}`,
 
         .. math::
             [\mathrm{prox}_{\lambda I_{>=0}}(\mb{v})]_i =
             \begin{cases}
-            v_i, & \text{if } v_i \geq 0 \\
-            0, & \text{else}.
+            v_i\,, & \text{if } v_i \geq 0 \\
+            0\,, & \text{otherwise} \;.
             \end{cases}
 
         Args:
-            v :  Input array :math:`\mb{v}`.
+            v : Input array :math:`\mb{v}`.
             lam : Proximal parameter :math:`\lambda` (has no effect).
             kwargs: Additional arguments that may be used by derived
                 classes.

scico/functional/_norm.py

@@ -166,7 +166,7 @@ def prox(
 
         .. math::
             \mathrm{prox}_{\lambda \| \cdot \|_2}(\mb{v})
-        = \mb{v} \left(1 - \frac{\lambda}{\norm{v}_2} \right)_+ \;,
+            = \mb{v} \left(1 - \frac{\lambda}{\norm{v}_2} \right)_+ \;,
 
         where
 

scico/linop/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2021 by SCICO Developers
+# Copyright (C) 2021-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/linop/_diff.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the
@@ -23,8 +23,6 @@
 from ._linop import LinearOperator
 from ._stack import LinearOperatorStack
 
-__author__ = """Luke Pfister <[email protected]>, Michael McCann <[email protected]>"""
-
 
 class FiniteDifference(LinearOperatorStack):
     """Finite Difference operator.

scico/linop/optics.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2021 by SCICO Developers
+# Copyright (C) 2021-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/linop/radon_astra.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/linop/radon_svmbir.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2021 by SCICO Developers
+# Copyright (C) 2021-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/numpy/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the
@@ -13,7 +13,6 @@
 module is a work in progress and therefore not all functions are
 wrapped. Functions that have not been wrapped yet have WARNING text in
 their documentation, below.
-
 """
 
 import sys

scico/numpy/_create.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2021 by SCICO Developers
+# Copyright (C) 2021-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/numpy/_util.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/operator/biconvolve.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the

scico/scipy/special.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2020-2021 by SCICO Developers
+# Copyright (C) 2020-2022 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the
@@ -16,7 +16,6 @@
 :mod:`jax.scipy.special`.
 """
 
-__author__ = "Luke Pfister <[email protected]>"
 
 import sys