Docs improvements: CSS and explicit formatting (#28)

docs/source/contributing.rst

@@ -12,10 +12,16 @@ Contributing
     div.document li > p {
        margin-bottom: 4px !important;
     }
-    div.document li {
+    div.document ul > li {
       list-style: square outside !important;
       margin-left: 1em !important;
     }
+    section {
+      padding-bottom: 1em;
+    }
+    ul {
+      margin-bottom: 1em;
+    }
     </style>
 
 
@@ -90,7 +96,6 @@ Contributing Code
 - Branches should be named in the form `<username>/<brief-description>`,
   where `<brief-description>` provides a highly condensed description of the purpose of the branch (e.g. `address_todo`), and may include an issue number if appropriate (e.g. `fix_223`).
 
-|
 
 A feature development workflow might look like this:
 
@@ -328,7 +333,6 @@ To run the type checker on the ``scico`` module:
 
 
 
-
 Building Documentation
 ======================
 
@@ -340,7 +344,6 @@ To build a local copy of the docs, from the repo root directory, do
 
 
 
-
 Test Coverage
 -------------
 

docs/source/functional.rst

@@ -1,6 +1,28 @@
 Functionals and Losses
 ======================
 
+.. raw:: html
+
+    <style type='text/css'>
+    div.document ul blockquote {
+       margin-bottom: 8px !important;
+    }
+    div.document li > p {
+       margin-bottom: 4px !important;
+    }
+    div.document ul > li {
+      list-style: square outside !important;
+      margin-left: 1em !important;
+    }
+    section {
+      padding-bottom: 1em;
+    }
+    ul {
+      margin-bottom: 1em;
+    }
+    </style>
+
+
 A functional maps an :code:`array-like` to a scalar; abstractly, a functional is
 a mapping from :math:`\mathbb{R}^n` or :math:`\mathbb{C}^n` to :math:`\mathbb{R}`.
 
@@ -14,10 +36,9 @@ A functional ``f`` can have three core operations.
 * Gradient
    - ``f.grad(x)`` returns the gradient of the functional evaluated at :math:`\mb{x}`.
    - Calculated using JAX reverse-mode automatic differentiation, exposed through :func:`scico.grad`.
-   - A functional that is smooth has the attribute ``f.is_smooth == True``
+   - A functional that is smooth has the attribute ``f.is_smooth == True``.
    - NOTE:  The gradient of a functional ``f`` can be evaluated even if ``f.is_smooth == False``.  All that is required is that the functional can be evaluated, ``f.has_eval == True``.  However, the result may not be a valid gradient (or subgradient) for all inputs :math:`\mb{x}`.
 
-
 * Proximal operator
    - The proximal operator of a functional :math:`f : \mathbb{R}^n \to \mathbb{R}` is the mapping
      :math:`\mathrm{prox}_f : \mathbb{R}^n \times \mathbb{R} \to \mathbb{R}^n` defined as
@@ -39,6 +60,7 @@ Proximal Calculus
 
 We support a limited subset of proximal calculus rules.
 
+
 Scaled Functionals
 ******************
 
@@ -106,3 +128,7 @@ Adding New Functionals
 
 Losses
 ------
+
+.. todo::
+
+   Content missing here

docs/source/overview.rst

@@ -11,10 +11,16 @@ Overview
     div.document li > p {
        margin-bottom: 4px !important;
     }
-    div.document li {
+    div.document ul > li {
       list-style: square outside !important;
       margin-left: 1em !important;
     }
+    section {
+      padding-bottom: 1em;
+    }
+    ul {
+      margin-bottom: 1em;
+    }
     </style>
 
 
@@ -41,60 +47,35 @@ SCICO is designed to solve problems of the form
 
    \argmin_{\mb{x}} \; f(\mb{x}) + \sum_{r=1}^R g_r(C_r (\mb{x})),
 
-with :math:`\mb{x} \in  \mathbb{R}^{n}` representing the reconstruction, e.g.,  a 1D, 2D, 3D, or 3D+time image,
-:math:`C_r:  \mathbb{R}^{n} \to \mathbb{R}^{m_r}` being regularization operators,
-and :math:`f: \mathbb{R}^{n} \to \mathbb{R}` and :math:`g_r: \mathbb{R}^{m_r} \to \mathbb{R}` being functionals associated with the data fidelity and regularization, respectively.
-
+with :math:`\mb{x} \in \mathbb{R}^{n}` representing the reconstruction, e.g., a 1D, 2D, 3D, or 3D+time image, :math:`C_r: \mathbb{R}^{n} \to \mathbb{R}^{m_r}` being regularization operators, and :math:`f: \mathbb{R}^{n} \to \mathbb{R}` and :math:`g_r: \mathbb{R}^{m_r} \to \mathbb{R}` being functionals associated with the data fidelity and regularization, respectively.
 
-In a typical computational imaging problem, we have a `forward model`
-that models the data acquisition process.  We denote this forward
-model by the (possibly nonlinear) operator :math:`A`.
+In a typical computational imaging problem, we have a `forward model` that models the data acquisition process.  We denote this forward model by the (possibly nonlinear) operator :math:`A`.
 
 We want to find :math:`\mb{x}` such that :math:`\mb{y} \approx A(\mb{x})`
 in some appropriate sense. This discrepency is measured in our data fidelity, or `loss`, function
 
 .. math::
    f(\mb{x}) = L(A(\mb{x}), \mb{y}) \,,
 
-where :math:`L` is a `functional` that maps a vector (or array) into
-a scalar.  A common choice is :math:`f(\mb{x}) = \norm{\mb{y} - A(\mb{x})}_2^2`.
-The SCICO :class:`.Loss` object encapsulates the data
-:math:`\mb{y}`, the forward model :math:`A`, and the functional
-:math:`L` in a single object.  A library of functionals and losses
-are implemented in :mod:`.functional` and :mod:`.loss`,
-respectively.
+where :math:`L` is a `functional` that maps a vector (or array) into a scalar.  A common choice is :math:`f(\mb{x}) = \norm{\mb{y} - A(\mb{x})}_2^2`.  The SCICO :class:`.Loss` object encapsulates the data :math:`\mb{y}`, the forward model :math:`A`, and the functional :math:`L` in a single object.  A library of functionals and losses are implemented in :mod:`.functional` and :mod:`.loss`, respectively.
 
-Note that :math:`f(\mb{x})` can often be interpreted as the negative
-log likelihood of the candidate :math:`\mb{x}`, given the measurements
-:math:`\mb{y}` and an underlying noise model.
+Note that :math:`f(\mb{x})` can often be interpreted as the negative log likelihood of the candidate :math:`\mb{x}`, given the measurements :math:`\mb{y}` and an underlying noise model.
 
-The functionals :math:`g_r(C_r (\mb{x}))` are regularization functionals.  The :math:`C_r` are operators,
-usually linear operators.   Together, these terms encourage solutions that arex
-"simple" in some sense.  A popular choice is :math:`g = \norm{ \cdot }_1` and :math:`C` to be a :class:`.FiniteDifferece`
-linear operator; this combination promotes piecewise smooth solutions to the inverse problem.
+The functionals :math:`g_r(C_r (\mb{x}))` are regularization functionals.  The :math:`C_r` are operators, usually linear operators.  Together, these terms encourage solutions that arex "simple" in some sense.  A popular choice is :math:`g = \norm{ \cdot }_1` and :math:`C` to be a :class:`.FiniteDifferece` linear operator; this combination promotes piecewise smooth solutions to the inverse problem.
 
 
 Usage Examples
 --------------
 
-Usage examples are available as Python scripts and Jupyter Notebooks. Example
-scripts are located in ``examples/scripts``. The corresponding Jupyter Notebooks
-are provided in the ``scico-data`` submodule and symlinked to
-``examples/notebooks``. They are also viewable on `GitHub
-<https://github.com/lanl/scico-data/tree/main/notebooks>`_ and in the
-documentation :ref:`example_notebooks`.
+Usage examples are available as Python scripts and Jupyter Notebooks. Example scripts are located in ``examples/scripts``. The corresponding Jupyter Notebooks are provided in the ``scico-data`` submodule and symlinked to ``examples/notebooks``. They are also viewable on `GitHub <https://github.com/lanl/scico-data/tree/main/notebooks>`_ and in the documentation :ref:`example_notebooks`.
 
 
 Related Projects
 ----------------
 
-The SCICO library is inspired by the `GlobalBiolm <https://github.com/Biomedical-Imaging-Group/GlobalBioIm>`_ MATLAB package,
-which provides a similar object-oriented design for solving computational imaging problems. `Pycsou <https://github.com/matthieumeo/pycsou>`_ is a similar
-Python library for inverse problems that is also inspired by GlobalBioIm.
+The SCICO library is inspired by the `GlobalBiolm <https://github.com/Biomedical-Imaging-Group/GlobalBioIm>`_ MATLAB package, which provides a similar object-oriented design for solving computational imaging problems. `Pycsou <https://github.com/matthieumeo/pycsou>`_ is a similar Python library for inverse problems that is also inspired by GlobalBioIm.
 
-A key advantage of SCICO over these libraries is the usage of JAX, which provides automatic hardware acceleration, automatic differentiation,
-and automatic adjoint calculations.  Moreover, as JAX is a machine learning library, state of the art Plug-and-Play regularizers such as DnCNN
-can specified, trained, and implemented in the same software package.
+A key advantage of SCICO over these libraries is the usage of JAX, which provides automatic hardware acceleration, automatic differentiation, and automatic adjoint calculations.  Moreover, as JAX is a machine learning library, state of the art Plug-and-Play regularizers such as DnCNN can specified, trained, and implemented in the same software package.
 
 
 Other related projects that may be of interest include:

docs/source/style.rst

@@ -13,10 +13,16 @@ Style Guide
     div.document li > p {
        margin-bottom: 4px !important;
     }
-    div.document li {
+    div.document ul > li {
       list-style: square outside !important;
       margin-left: 1em !important;
     }
+    section {
+      padding-bottom: 1em;
+    }
+    ul {
+      margin-bottom: 1em;
+    }
     </style>
 
 
@@ -100,7 +106,6 @@ Things to avoid:
    - Protected: Use a single underscore, ``_``, for protected access
    - Pseudo-private: Use double underscores, ``_``, for pseudo-private access via name mangling.
 
-|
 
 Displaying and Printing Strings
 -------------------------------
@@ -114,8 +119,6 @@ Prefer to use Python f-strings, rather than `.format` or `%` syntax.
     print(f"The state is {state}")  # Preferred
 
 
-
-
 Imports
 -------
 
@@ -126,7 +129,6 @@ Usage of ``import`` statements should be reserved for packages and modules only
 -  Use ``from x import y as z`` if two modules named ``y`` are imported or if ``y`` is too long of a name.
 -  Use ``import y as z`` when ``z`` is a standard abbreviation like ``import numpy as np``.
 
-|
 
 Variables
 ---------
@@ -146,7 +148,6 @@ Apart from naming conventions there are a few extra documentation and coding pra
    - Avoid global variables.
    - A function can refer to variables defined in enclosing functions but cannot assign to them.
 
-|
 
 Parameters
 ----------
@@ -193,7 +194,6 @@ There are three important stlyle components for parameters:
 
    - For documentation purposes, ``NoneType`` or ``None`` should be written with double backticks
 
-|
 
 Docstrings
 ----------
@@ -406,8 +406,8 @@ The following are sections that can be added to functions, modules, classes, or
       with a ``...``
 
       >>> np.add([[1, 2], [3, 4]],
-      ...         [[5, 6], [7, 8]]) 
-      array([[ 6,  8], 
+      ...         [[5, 6], [7, 8]])
+      array([[ 6,  8],
              [10, 12]])
 
       """

docs/source/team.rst

@@ -11,10 +11,16 @@ SCICO Contributors
     div.document li > p {
        margin-bottom: 4px !important;
     }
-    div.document li {
+    div.document ul > li {
       list-style: square outside !important;
       margin-left: 1em !important;
     }
+    section {
+      padding-bottom: 1em;
+    }
+    ul {
+      margin-bottom: 1em;
+    }
     </style>
 
 
@@ -28,11 +34,9 @@ Core Developers
 - `Michael McCann <https://github.com/Michael-T-McCann>`_
 - `Brendt Wohlberg <https://github.com/bwohlberg>`_
 
-|
 
 Contributors
 ============
 
 - `Oleg Korobkin <https://github.com/korobkin>`_ (BlockArray improvements)
 - `Yanpeng Yuan <https://github.com/yanpeng7>`_ (Improvements to ASTRA interface)
-