gh-346: enforce NumPy docstrings + use static typing in docs (#347)

Closes #346. Working towards #188.

The main changes here have been:
- Remove all types in the docstrings in favour of proper static typing
(being added in #308)
- Switch from `numpydoc` to `sphinx.ext.napolean` due to
numpy/numpydoc#196

Have had to change the references to `[1]` rather than `[1]_` due to
this bug, sphinx-doc/sphinx#9689. Hopefully
this can be fixed in the future.

Example:
`glass.lensing.from_convergence`
<img width="781" alt="image"
src="https://github.com/user-attachments/assets/9b6fd087-686a-4a5c-a77a-f8a3ec9fc3e2">

Raised #350, #351.

Author: paddyroddy

docs/conf.py

@@ -23,12 +23,12 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "numpydoc",
-    "sphinx.ext.intersphinx",
-    "sphinxcontrib.katex",
     "matplotlib.sphinxext.plot_directive",
     "nbsphinx",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinxcontrib.katex",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -42,7 +42,7 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
+# The theme to use for HTML and HTML Help pages. See the documentation for
 # a list of builtin themes.
 #
 html_theme = "furo"
@@ -69,15 +69,12 @@
 
 # -- autodoc -----------------------------------------------------------------
 
-autodoc_typehints = "none"
+autodoc_typehints = "description"
 
 
-# -- numpydoc ----------------------------------------------------------------
+# -- napoleon ----------------------------------------------------------------
 
-# Whether to create a Sphinx table of contents for the lists of class methods
-# and attributes. If a table of contents is made, Sphinx expects each entry to
-# have a separate page.
-numpydoc_class_members_toctree = False
+napoleon_google_docstring = False
 
 
 # -- plot_directive ----------------------------------------------------------

glass/core/__init__.py

@@ -7,4 +7,4 @@
 The :mod:`glass.core` module contains core functionality for developing
 GLASS modules.
 
-"""  # noqa: D205, D400, D415
+"""  # noqa: D205, D400

glass/core/algorithm.py

@@ -20,13 +20,13 @@ def nnls(
     """
     Compute a non-negative least squares solution.
 
-    Implementation of the algorithm due to [1]_ as described in [2]_.
+    Implementation of the algorithm due to [1] as described in [2].
 
     References
     ----------
-    .. [1] Lawson, C. L. and Hanson, R. J. (1995), Solving Least Squares
+    * [1] Lawson, C. L. and Hanson, R. J. (1995), Solving Least Squares
         Problems. doi: 10.1137/1.9781611971217
-    .. [2] Bro, R. and De Jong, S. (1997), A fast
+    * [2] Bro, R. and De Jong, S. (1997), A fast
         non-negativity-constrained least squares algorithm. J.
         Chemometrics, 11, 393-401.
 

glass/fields.py

@@ -5,7 +5,7 @@
 .. currentmodule:: glass
 
 The following functions provide functionality for simulating random
-fields on the sphere.  This is done in the form of HEALPix maps.
+fields on the sphere. This is done in the form of HEALPix maps.
 
 Functions
 ---------
@@ -22,7 +22,7 @@
 
 .. autofunction:: getcl
 
-"""  # noqa: D205, D400, D415
+"""  # noqa: D205, D400
 
 from __future__ import annotations
 
@@ -163,7 +163,7 @@ def gaussian_gls(
 
     Depending on the given arguments, this truncates the angular power spectra
     to ``lmax``, removes all but ``ncorr`` correlations between fields, and
-    applies the HEALPix pixel window function of the given ``nside``.  If no
+    applies the HEALPix pixel window function of the given ``nside``. If no
     arguments are given, no action is performed.
 
     """
@@ -221,7 +221,7 @@ def generate_gaussian(
     ``nside``.
 
     The optional argument ``ncorr`` can be used to artificially limit now many
-    realised fields are correlated.  This saves memory, as only `ncorr` previous
+    realised fields are correlated. This saves memory, as only `ncorr` previous
     fields need to be kept.
 
     The ``gls`` array must contain the auto-correlation of each new field
@@ -329,18 +329,15 @@ def getcl(cls, i, j, lmax=None):
 
     Parameters
     ----------
-    cls : list of array_like
+    cls:
         List of angular power spectra in *GLASS* ordering.
-    i, j : int
-        Combination of indices to return.
-    lmax : int, optional
+    i:
+        Indices to return.
+    j:
+        Indices to return.
+    lmax:
         Truncate the returned spectrum at this mode number.
 
-    Returns
-    -------
-    cl : array_like
-        The angular power spectrum for indices *i* and *j*.
-
     """
     if j > i:
         i, j = j, i
@@ -360,28 +357,25 @@ def effective_cls(
     Compute effective angular power spectra from weights.
 
     Computes a linear combination of the angular power spectra *cls*
-    using the factors provided by *weights1* and *weights2*.  Additional
+    using the factors provided by *weights1* and *weights2*. Additional
     axes in *weights1* and *weights2* produce arrays of spectra.
 
+    Returns a dictionary of effective angular power spectra, where keys
+    correspond to the leading axes of *weights1* and *weights2*.
+
     Parameters
     ----------
-    cls : (N,) list of array_like
+    cls:
         Angular matter power spectra to combine, in *GLASS* ordering.
-    weights1 : (N, \\*M1) array_like
-        Weight factors for spectra.  The first axis must be equal to the
-        number of fields.
-    weights2 : (N, \\*M2) array_like, optional
-        Second set of weights.  If not given, *weights1* is used.
-    lmax : int, optional
-        Truncate the angular power spectra at this mode number.  If not
+    weights1:
+        Weight factors for spectra. The first axis must be equal to
+        the number of fields.
+    weights2:
+        Second set of weights. If not given, *weights1* is used.
+    lmax:
+        Truncate the angular power spectra at this mode number. If not
         given, the longest input in *cls* will be used.
 
-    Returns
-    -------
-    cls : (\\*M1, \\*M2, LMAX+1) array_like
-        Dictionary of effective angular power spectra, where keys
-        correspond to the leading axes of *weights1* and *weights2*.
-
     """
     from itertools import combinations_with_replacement, product
 

glass/galaxies.py

@@ -15,7 +15,7 @@
 .. autofunction:: galaxy_shear
 .. autofunction:: gaussian_phz
 
-"""  # noqa: D205, D400, D415
+"""  # noqa: D205, D400
 
 from __future__ import annotations
 
@@ -45,20 +45,17 @@ def redshifts(
     This function samples *n* redshifts from a distribution that follows
     the given radial window function *w*.
 
+    Returns random redshifts following the radial window function.
+
     Parameters
     ----------
-    n : int or array_like
-        Number of redshifts to sample.  If an array is given, the
+    n:
+        Number of redshifts to sample. If an array is given, the
         results are concatenated.
-    w : :class:`~glass.RadialWindow`
+    w:
         Radial window function.
-    rng : :class:`~numpy.random.Generator`, optional
-        Random number generator.  If not given, a default RNG is used.
-
-    Returns
-    -------
-    z : array_like
-        Random redshifts following the radial window function.
+    rng:
+        Random number generator. If not given, a default RNG is used.
 
     """
     return redshifts_from_nz(n, w.za, w.wa, rng=rng, warn=False)
@@ -77,31 +74,31 @@ def redshifts_from_nz(
 
     The function supports sampling from multiple populations of
     redshifts if *count* is an array or if there are additional axes in
-    the *z* or *nz* arrays.  In this case, the shape of *count* and the
+    the *z* or *nz* arrays. In this case, the shape of *count* and the
     leading dimensions of *z* and *nz* are broadcast to a common shape,
     and redshifts are sampled independently for each extra dimension.
     The results are concatenated into a flat array.
 
+    Returns redshifts sampled from the given source distribution. For
+    inputs with extra dimensions, returns a flattened 1-D array of
+    samples from all populations.
+
     Parameters
     ----------
-    count : int or array_like
-        Number of redshifts to sample.  If an array is given, its shape
+    count:
+        Number of redshifts to sample. If an array is given, its shape
         is broadcast against the leading axes of *z* and *nz*.
-    z, nz : array_like
-        Source distribution.  Leading axes are broadcast against the
+    z:
+        Source distribution. Leading axes are broadcast against the
         shape of *count*.
-    rng : :class:`~numpy.random.Generator`, optional
-        Random number generator.  If not given, a default RNG is used.
-    warn : bool
+    nz:
+        Source distribution. Leading axes are broadcast against the
+        shape of *count*.
+    rng:
+        Random number generator. If not given, a default RNG is used.
+    warn:
         Throw relevant warnings.
 
-    Returns
-    -------
-    redshifts : array_like
-        Redshifts sampled from the given source distribution.  For
-        inputs with extra dimensions, returns a flattened 1-D array of
-        samples from all populations.
-
     """
     if warn:
         warnings.warn(
@@ -158,22 +155,26 @@ def galaxy_shear(  # noqa: PLR0913
     Takes lensing maps for convergence and shear and produces a lensed
     ellipticity (shear) for each intrinsic galaxy ellipticity.
 
+    Returns an array of complex-valued observed galaxy shears
+    (lensed ellipticities).
+
     Parameters
     ----------
-    lon, lat : array_like
-        Arrays for galaxy longitudes and latitudes.
-    eps : array_like
+    lon:
+        Array for galaxy longitudes.
+    lat:
+        Array for galaxy latitudes.
+    eps:
         Array of galaxy :term:`ellipticity`.
-    kappa, gamma1, gamma2 : array_like
-        HEALPix maps for convergence and two components of shear.
-    reduced_shear : bool, optional
-        If ``False``, galaxy shears are not reduced by the convergence.
-        Default is ``True``.
-
-    Returns
-    -------
-    she : array_like
-        Array of complex-valued observed galaxy shears (lensed ellipticities).
+    kappa:
+        HEALPix map for convergence.
+    gamma1:
+        HEALPix maps for a component of shear.
+    gamma2:
+        HEALPix maps for a component of shear.
+    reduced_shear:
+        If ``False``, galaxy shears are not reduced
+        by the convergence. Default is ``True``.
 
     """
     nside = healpix.npix2nside(np.broadcast(kappa, gamma1, gamma2).shape[-1])
@@ -218,40 +219,38 @@ def gaussian_phz(
 
     A simple toy model of photometric redshift errors that assumes a
     Gaussian error with redshift-dependent standard deviation
-    :math:`\sigma(z) = (1 + z) \sigma_0` [1]_.
+    :math:`\sigma(z) = (1 + z) \sigma_0` [1].
+
+    Returns photometric redshifts assuming Gaussian errors, of the same
+    shape as *z*.
 
     Parameters
     ----------
-    z : array_like
+    z:
         True redshifts.
-    sigma_0 : float or array_like
+    sigma_0:
         Redshift error in the tomographic binning at zero redshift.
-    lower, upper : float or array_like, optional
+    lower:
         Bounds for the returned photometric redshifts.
-    rng : :class:`~numpy.random.Generator`, optional
-        Random number generator.  If not given, a default RNG is used.
-
-    Returns
-    -------
-    phz : array_like
-        Photometric redshifts assuming Gaussian errors, of the same
-        shape as *z*.
+    upper:
+        Bounds for the returned photometric redshifts.
+    rng:
+        Random number generator. If not given, a default RNG is used.
 
     Warnings
     --------
     The *lower* and *upper* bounds are implemented using plain rejection
-    sampling from the non-truncated normal distribution.  If bounds are
+    sampling from the non-truncated normal distribution. If bounds are
     used, they should always contain significant probability mass.
 
     See Also
     --------
-    glass.tomo_nz_gausserr :
-        Create tomographic redshift distributions assuming the same
-        model.
+    glass.tomo_nz_gausserr:
+        Create tomographic redshift distributions assuming the same model.
 
     References
     ----------
-    .. [1] Amara A., Réfrégier A., 2007, MNRAS, 381, 1018.
+    * [1] Amara A., Réfrégier A., 2007, MNRAS, 381, 1018.
            doi:10.1111/j.1365-2966.2007.12271.x
 
     Examples