Improve documentation for linop.optics (#233)

* Docstring cleanup

* Equation layout change

* Docstring fixes

* Improve documentation

* Fix test shadowing bug

* Minor docs improvements

* Minor edits

* Add equation number

* Tweaks from discussion with Andrew

* Some docs improvements

* Fix formatting by wrong version of black

* Update contributors

* Docs improvements

* Typo fix

* Add reference

* Add link for contributor

* Docs improvements

* Docs style compliance

* Docs improvements

Co-authored-by: Mike McCann <[email protected]>

docs/source/references.bib

@@ -366,6 +366,16 @@ @Article {menon-2007-demosaicing
   doi =		 {10.1109/tip.2006.884928}
 }
 
+@Book {paganin-2006-coherent,
+  doi =		 {10.1093/acprof:oso/9780198567288.001.0001},
+  isbn =	 {9780198567288},
+  year =	 2006,
+  month =	 Jan,
+  publisher =	 {Oxford University Press},
+  author =	 {David Paganin},
+  title =	 {Coherent X-Ray Optics}
+}
+
 @Article {parikh-2014-proximal,
   title =	 {Proximal algorithms},
   author =	 {Parikh, Neal and Boyd, Stephen},

docs/source/team.rst

@@ -42,3 +42,4 @@ Contributors
 - `Oleg Korobkin <https://github.com/korobkin>`_ (BlockArray improvements)
 - `Yanpeng Yuan <https://github.com/yanpeng7>`_ (ASTRA interface improvements)
 - `Saurav Maheshkar <https://github.com/SauravMaheshkar>`_ (Improvements to pre-commit configuration)
+- `Andrew Leong <https://scholar.google.com/citations?user=-2wRWbcAAAAJ&hl=en>`_ (Improvements to optics module documentation)

scico/_generic_operators.py

@@ -613,7 +613,7 @@ def T(self) -> LinearOperator:
 
         Return a new :class:`LinearOperator` that implements the
         transpose of this :class:`LinearOperator`. For a real-valued
-        LinearOperator `A` (`A.input_dtype` is``np.float32`` or
+        LinearOperator `A` (`A.input_dtype` is ``np.float32`` or
         ``np.float64``), the LinearOperator `A.T` implements the
         adjoint: `A.T(y) == A.adj(y)`. For a complex-valued
         LinearOperator `A` (`A.input_dtype` is ``np.complex64`` or
@@ -722,8 +722,7 @@ class ComposedLinearOperator(LinearOperator):
     """A LinearOperator formed by the composition of two LinearOperators."""
 
     def __init__(self, A: LinearOperator, B: LinearOperator, jit: bool = False):
-        r"""ComposedLinearOperator init method.
-
+        r"""
         A ComposedLinearOperator `AB` implements `AB @ x == A @ B @ x`.
         The LinearOperators `A` and `B` are stored as attributes of
         the ComposedLinearOperator.
@@ -741,12 +740,12 @@ def __init__(self, A: LinearOperator, B: LinearOperator, jit: bool = False):
         """
         if not isinstance(A, LinearOperator):
             raise TypeError(
-                "The first argument to ComposedLinearOpeator must be a LinearOperator; "
+                "The first argument to ComposedLinearOperator must be a LinearOperator; "
                 f"got {type(A)}"
             )
         if not isinstance(B, LinearOperator):
             raise TypeError(
-                "The second argument to ComposedLinearOpeator must be a LinearOperator; "
+                "The second argument to ComposedLinearOperator must be a LinearOperator; "
                 f"got {type(B)}"
             )
         if A.input_shape != B.output_shape:

scico/array.py

@@ -199,7 +199,8 @@ def is_nested(x: Any) -> bool:
         x: Object to be tested.
 
     Returns:
-        True if `x` is a list/tuple of list/tuples, False otherwise.
+        ``True`` if `x` is a list/tuple of list/tuples, otherwise
+        ``False``.
 
 
     Example:
@@ -220,11 +221,11 @@ def is_real_dtype(dtype: DType) -> bool:
     """Determine whether a dtype is real.
 
     Args:
-        dtype: A numpy or scico.numpy dtype (e.g. np.float32,
-               snp.complex64).
+        dtype: A numpy or scico.numpy dtype (e.g. ``np.float32``,
+               ``np.complex64``).
 
     Returns:
-        False if the dtype is complex, otherwise True.
+        ``False`` if the dtype is complex, otherwise ``True``.
     """
     return snp.dtype(dtype).kind != "c"
 
@@ -237,7 +238,7 @@ def is_complex_dtype(dtype: DType) -> bool:
                ``np.complex64``).
 
     Returns:
-        True if the dtype is complex, otherwise False.
+        ``True`` if the dtype is complex, otherwise ``False``.
     """
     return snp.dtype(dtype).kind == "c"
 
@@ -246,8 +247,8 @@ def real_dtype(dtype: DType) -> DType:
     """Construct the corresponding real dtype for a given complex dtype.
 
     Construct the corresponding real dtype for a given complex dtype,
-    e.g. the real dtype corresponding to `np.complex64` is
-    `np.float32`.
+    e.g. the real dtype corresponding to ``np.complex64`` is
+    ``np.float32``.
 
     Args:
         dtype: A complex numpy or scico.numpy dtype (e.g. ``np.complex64``,