gh-188: add docstrings to all functions and tidy docs (#381)

Co-authored-by: Saransh Chopra <[email protected]>
Co-authored-by: Nicolas Tessore <[email protected]>

docs/conf.py

@@ -25,9 +25,11 @@
 extensions = [
     "matplotlib.sphinxext.plot_directive",
     "nbsphinx",
+    "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx_autodoc_typehints",
     "sphinxcontrib.katex",
 ]
 
@@ -62,8 +64,8 @@
 # This config value contains the locations and names of other projects that
 # should be linked to in this documentation.
 intersphinx_mapping = {
+    "numpy": ("https://numpy.org/doc/stable", None),
     "python": ("https://docs.python.org/3", None),
-    "numpy": ("https://numpy.org/doc/stable/", None),
 }
 
 
@@ -74,9 +76,18 @@
 
 # -- napoleon ----------------------------------------------------------------
 
+napoleon_custom_sections = [
+    ("Returns", "params_style"),
+    ("Yields", "params_style"),
+]
 napoleon_google_docstring = False
 
 
+# -- sphinx-autodoc-typehints ------------------------------------------------
+
+always_use_bars_union = True
+
+
 # -- plot_directive ----------------------------------------------------------
 
 # Whether to show a link to the source in HTML (default: True).

glass/core/algorithm.py

@@ -18,13 +18,37 @@ def nnls(
 
     Implementation of the algorithm due to [1] as described in [2].
 
+    Parameters
+    ----------
+    a
+        The matrix.
+    b
+        The vector.
+    tol
+        The tolerance for convergence.
+    maxiter
+        The maximum number of iterations.
+
+    Returns
+    -------
+        The non-negative least squares solution.
+
+    Raises
+    ------
+    ValueError
+        If ``a`` is not a matrix.
+    ValueError
+        If ``b`` is not a vector.
+    ValueError
+        If the shapes of ``a`` and ``b`` do not match.
+
     References
     ----------
     * [1] Lawson, C. L. and Hanson, R. J. (1995), Solving Least Squares
-        Problems. doi: 10.1137/1.9781611971217
+          Problems. doi: 10.1137/1.9781611971217
     * [2] Bro, R. and De Jong, S. (1997), A fast
-        non-negativity-constrained least squares algorithm. J.
-        Chemometrics, 11, 393-401.
+          non-negativity-constrained least squares algorithm. J.
+          Chemometrics, 11, 393-401.
 
     """
     a = np.asanyarray(a)

glass/core/array.py

@@ -15,7 +15,19 @@
 def broadcast_first(
     *arrays: npt.NDArray[np.float64],
 ) -> tuple[npt.NDArray[np.float64], ...]:
-    """Broadcast arrays, treating the first axis as common."""
+    """
+    Broadcast arrays, treating the first axis as common.
+
+    Parameters
+    ----------
+    arrays
+        The arrays to broadcast.
+
+    Returns
+    -------
+        The broadcasted arrays.
+
+    """
     arrays = tuple(np.moveaxis(a, 0, -1) if np.ndim(a) else a for a in arrays)
     arrays = np.broadcast_arrays(*arrays)
     return tuple(np.moveaxis(a, -1, 0) if np.ndim(a) else a for a in arrays)
@@ -33,8 +45,15 @@ def broadcast_leading_axes(
     """
     Broadcast all but the last N axes.
 
-    Returns the shape of the broadcast dimensions, and all input arrays
-    with leading axes matching that shape.
+    Parameters
+    ----------
+    args
+        The arrays and the number of axes to keep.
+
+    Returns
+    -------
+        The shape of the broadcast dimensions, and all input arrays
+        with leading axes matching that shape.
 
     Examples
     --------
@@ -75,7 +94,31 @@ def ndinterp(  # noqa: PLR0913
     right: float | None = None,
     period: float | None = None,
 ) -> npt.NDArray[np.float64]:
-    """Interpolate multi-dimensional array over axis."""
+    """
+    Interpolate multi-dimensional array over axis.
+
+    Parameters
+    ----------
+    x
+        The x-coordinates.
+    xp
+        The x-coordinates of the data points.
+    fp
+        The function values corresponding to the x-coordinates in *xp*.
+    axis
+        The axis to interpolate over.
+    left
+        The value to return for x < xp[0].
+    right
+        The value to return for x > xp[-1].
+    period
+        The period of the function, used for interpolating periodic data.
+
+    Returns
+    -------
+        The interpolated array.
+
+    """
     return np.apply_along_axis(
         partial(np.interp, x, xp),
         axis,
@@ -94,7 +137,23 @@ def trapz_product(
     ],
     axis: int = -1,
 ) -> npt.NDArray[np.float64]:
-    """Trapezoidal rule for a product of functions."""
+    """
+    Trapezoidal rule for a product of functions.
+
+    Parameters
+    ----------
+    f
+        The first function.
+    ff
+        The other functions.
+    axis
+        The axis along which to integrate.
+
+    Returns
+    -------
+        The integral of the product of the functions.
+
+    """
     x: npt.NDArray[np.float64]
     x, _ = f
     for x_, _ in ff:
@@ -118,7 +177,25 @@ def cumtrapz(
     dtype: npt.DTypeLike | None = None,
     out: npt.NDArray[np.float64] | None = None,
 ) -> npt.NDArray[np.float64]:
-    """Cumulative trapezoidal rule along last axis."""
+    """
+    Cumulative trapezoidal rule along last axis.
+
+    Parameters
+    ----------
+    f
+        The function values.
+    x
+        The x-coordinates.
+    dtype
+        The output data type.
+    out
+        The output array.
+
+    Returns
+    -------
+        The cumulative integral of the function.
+
+    """
     if out is None:
         out = np.empty_like(f, dtype=dtype)
 

glass/ext/__init__.py

@@ -8,6 +8,21 @@
 
 
 def _extend_path(path: list[str], name: str) -> list[str]:
+    """
+    Extend the path to include the "ext" submodules of packages.
+
+    Parameters
+    ----------
+    path
+        The path to extend.
+    name
+        The name of the package.
+
+    Returns
+    -------
+        The extended path.
+
+    """
     import os.path
     from pkgutil import extend_path