[WIP] Fix AstroPhot docstrings to explicit RST fields for Sphinx compatibility

.readthedocs.yaml

@@ -26,8 +26,6 @@ build:
     - graphviz
   jobs:
     pre_build:
-      # Build docstring jupyter notebooks
-      - "python make_docs.py"
       # Generate the Sphinx configuration for this Jupyter Book so it builds.
       - "jupyter-book config sphinx docs/source/"
       # Create font cache ahead of jupyter book

astrophot/fit/base.py

@@ -13,14 +13,13 @@ class BaseOptimizer:
     """
     Base optimizer object that other optimizers inherit from. Ensures consistent signature for the classes.
 
-    **Args:**
-    -  `model`: an AstroPhot_Model object that will have its (unlocked) parameters optimized [AstroPhot_Model]
-    -  `initial_state`: optional initialization for the parameters as a 1D tensor [tensor]
-    -  `relative_tolerance`: tolerance for counting success steps as: $0 < (\\chi_2^2 - \\chi_1^2)/\\chi_1^2 < \\text{tol}$ [float]
-    -  `verbose`: verbosity level for the optimizer [int]
-    -  `max_iter`: maximum allowed number of iterations [int]
-    -  `save_steps`: optional string for path to save the model at each step (fitter dependent), e.g. "model_step_{step}.hdf5" [str]
-    -  `fit_valid`: whether to fit while forcing parameters into valid range, or allow any value for each parameter. Default True [bool]
+    :param model: an AstroPhot_Model object that will have its (unlocked) parameters optimized [AstroPhot_Model]
+    :param initial_state: optional initialization for the parameters as a 1D Array [Array]
+    :param relative_tolerance: tolerance for counting success steps as: $0 < (\\chi_2^2 - \\chi_1^2)/\\chi_1^2 < \\text{tol}$ [float]
+    :param verbose: verbosity level for the optimizer [int]
+    :param max_iter: maximum allowed number of iterations [int]
+    :param save_steps: optional string for path to save the model at each step (fitter dependent), e.g. "model_step_{step}.hdf5" [str]
+    :param fit_valid: whether to fit while forcing parameters into valid range, or allow any value for each parameter. Default True [bool]
 
     """
 

astrophot/fit/gradient.py

@@ -25,12 +25,16 @@ class Grad(BaseOptimizer):
     The optimizer is instantiated with a set of initial parameters and optimization options provided by the user.
     The `fit` method performs the optimization, taking a series of gradient steps until a stopping criteria is met.
 
-    **Args:**
-    -  `likelihood` (str, optional): The likelihood function to use for the optimization. Defaults to "gaussian".
-    -  `method` (str, optional): the optimization method to use for the update step. Defaults to "NAdam".
-    -  `optim_kwargs` (dict, optional): a dictionary of keyword arguments to pass to the pytorch optimizer.
-    -  `patience` (int, optional): number of steps with no improvement before stopping the optimization. Defaults to 10.
-    -  `report_freq` (int, optional): frequency of reporting the optimization progress. Defaults to 10 steps.
+    :param likelihood: The likelihood function to use for the optimization. Defaults to "gaussian".
+    :type likelihood: str, optional
+    :param method: the optimization method to use for the update step. Defaults to "NAdam".
+    :type method: str, optional
+    :param optim_kwargs: a dictionary of keyword arguments to pass to the pytorch optimizer.
+    :type optim_kwargs: dict, optional
+    :param patience: number of steps with no improvement before stopping the optimization. Defaults to 10.
+    :type patience: int, optional
+    :param report_freq: frequency of reporting the optimization progress. Defaults to 10 steps.
+    :type report_freq: int, optional
     """
 
     def __init__(
@@ -164,13 +168,18 @@ class Slalom(BaseOptimizer):
     gradient descent algorithms, Slalom slows down considerably when trying to
     achieve very high precision.
 
-    **Args:**
-    -  `S` (float, optional): The initial step size for the Slalom optimizer. Defaults to 1e-4.
-    -  `likelihood` (str, optional): The likelihood function to use for the optimization. Defaults to "gaussian".
-    -  `report_freq` (int, optional): Frequency of reporting the optimization progress. Defaults to 10 steps.
-    -  `relative_tolerance` (float, optional): The relative tolerance for convergence. Defaults to 1e-4.
-    -  `momentum` (float, optional): The momentum factor for the Slalom optimizer. Defaults to 0.5.
-    -  `max_iter` (int, optional): The maximum number of iterations for the optimizer. Defaults to 1000.
+    :param S: The initial step size for the Slalom optimizer. Defaults to 1e-4.
+    :type S: float, optional
+    :param likelihood: The likelihood function to use for the optimization. Defaults to "gaussian".
+    :type likelihood: str, optional
+    :param report_freq: Frequency of reporting the optimization progress. Defaults to 10 steps.
+    :type report_freq: int, optional
+    :param relative_tolerance: The relative tolerance for convergence. Defaults to 1e-4.
+    :type relative_tolerance: float, optional
+    :param momentum: The momentum factor for the Slalom optimizer. Defaults to 0.5.
+    :type momentum: float, optional
+    :param max_iter: The maximum number of iterations for the optimizer. Defaults to 1000.
+    :type max_iter: int, optional
     """
 
     def __init__(

astrophot/fit/hmc.py

@@ -31,11 +31,10 @@ def new_configure(self, mass_matrix_shape, adapt_mass_matrix=True, options={}):
     """
     Sets up an initial mass matrix.
 
-    **Args:**
-    -  `mass_matrix_shape`: a dict that maps tuples of site names to the shape of
+    :param mass_matrix_shape: a dict that maps tuples of site names to the shape of
         the corresponding mass matrix. Each tuple of site names corresponds to a block.
-    -  `adapt_mass_matrix`: a flag to decide whether an adaptation scheme will be used.
-    -  `options`: tensor options to construct the initial mass matrix.
+    :param adapt_mass_matrix: a flag to decide whether an adaptation scheme will be used.
+    :param options: Array options to construct the initial mass matrix.
     """
     inverse_mass_matrix = {}
     for site_names, shape in mass_matrix_shape.items():
@@ -70,16 +69,24 @@ class HMC(BaseOptimizer):
     https://arxiv.org/abs/1701.02434, and
     http://www.mcmchandbook.net/HandbookChapter5.pdf
 
-    **Args:**
-    -  `max_iter` (int, optional): The number of sampling steps to perform. Defaults to 1000.
-    -  `epsilon` (float, optional): The length of the integration step to perform for each leapfrog iteration. The momentum update will be of order epsilon * score. Defaults to 1e-5.
-    -  `leapfrog_steps` (int, optional): Number of steps to perform with leapfrog integrator per sample of the HMC. Defaults to 10.
-    -  `inv_mass` (float or array, optional): Inverse Mass matrix (covariance matrix) which can tune the behavior in each dimension to ensure better mixing when sampling. Defaults to the identity.
-    -  `progress_bar` (bool, optional): Whether to display a progress bar during sampling. Defaults to True.
-    -  `prior` (distribution, optional): Prior distribution for the parameters. Defaults to None.
-    -  `warmup` (int, optional): Number of warmup steps before actual sampling begins. Defaults to 100.
-    -  `hmc_kwargs` (dict, optional): Additional keyword arguments for the HMC sampler. Defaults to {}.
-    -  `mcmc_kwargs` (dict, optional): Additional keyword arguments for the MCMC process. Defaults to {}.
+    :param max_iter: The number of sampling steps to perform. Defaults to 1000.
+    :type max_iter: int, optional
+    :param epsilon: The length of the integration step to perform for each leapfrog iteration. The momentum update will be of order epsilon * score. Defaults to 1e-5.
+    :type epsilon: float, optional
+    :param leapfrog_steps: Number of steps to perform with leapfrog integrator per sample of the HMC. Defaults to 10.
+    :type leapfrog_steps: int, optional
+    :param inv_mass: Inverse Mass matrix (covariance matrix) which can tune the behavior in each dimension to ensure better mixing when sampling. Defaults to the identity.
+    :type inv_mass: float or array, optional
+    :param progress_bar: Whether to display a progress bar during sampling. Defaults to True.
+    :type progress_bar: bool, optional
+    :param prior: Prior distribution for the parameters. Defaults to None.
+    :type prior: distribution, optional
+    :param warmup: Number of warmup steps before actual sampling begins. Defaults to 100.
+    :type warmup: int, optional
+    :param hmc_kwargs: Additional keyword arguments for the HMC sampler. Defaults to {}.
+    :type hmc_kwargs: dict, optional
+    :param mcmc_kwargs: Additional keyword arguments for the MCMC process. Defaults to {}.
+    :type mcmc_kwargs: dict, optional
 
     """
 
@@ -122,8 +129,8 @@ def fit(
 
         Records the chain for later examination.
 
-        **Args:**
-            state (torch.Tensor, optional): Model parameters as a 1D tensor.
+        :param state: Model parameters as a 1D Array.
+        :type state: Array, optional
 
         """
 

astrophot/fit/iterative.py

@@ -36,9 +36,8 @@ class Iter(BaseOptimizer):
     is not worthwhile for a single model to spend lots of time optimizing when
     its neighbors havent converged.
 
-    **Args:**
-    -    `max_iter`: Maximum number of iterations, defaults to 100.
-    -    `lm_kwargs`: Keyword arguments to pass to `LM` optimizer.
+    :param max_iter: Maximum number of iterations, defaults to 100.
+    :param lm_kwargs: Keyword arguments to pass to `LM` optimizer.
     """
 
     def __init__(
@@ -165,14 +164,15 @@ class IterParam(BaseOptimizer):
     likely better to optimize the full problem with LM as, when it works, LM is
     faster than the IterParam method.
 
-    Args:
-      chunks (Union[int, tuple]): Specify how to break down the model
-        parameters. If an integer, at each iteration the algorithm will break the
-        parameters into groups of that size. If a tuple, should be a tuple of
-        arrays of length num_dimensions which act as selectors for the parameters
-        to fit (1 to include, 0 to exclude). Default: 50
-      chunk_order (str): How to iterate through the chunks. Should be one of: random,
-        sequential. Default: sequential
+    :param chunks: Specify how to break down the model parameters. If an integer,
+      at each iteration the algorithm will break the parameters into groups of
+      that size. If a tuple, it should be a tuple of arrays of length
+      num_dimensions which act as selectors for the parameters to fit (1 to
+      include, 0 to exclude). Default: 50.
+    :type chunks: Union[int, tuple]
+    :param chunk_order: How to iterate through the chunks. Should be one of:
+      ``"random"``, ``"sequential"``. Default: ``"sequential"``.
+    :type chunk_order: str
     """
 
     def __init__(

astrophot/fit/lm.py

@@ -82,28 +82,28 @@ class LM(BaseOptimizer):
     by Henri Gavin on which much of the AstroPhot LM implementation is
     based::
 
-    ```{latex}
+    .. code-block:: text
     @article{Gavin2019,
         title={The Levenberg-Marquardt algorithm for nonlinear least squares curve-fitting problems},
         author={Gavin, Henri P},
         journal={Department of Civil and Environmental Engineering, Duke University},
         volume={19},
         year={2019}
     }
-    ```
+
 
     as well as the paper on LM geodesic acceleration by Mark
     Transtrum::
 
-    ```{latex}
+    .. code-block:: text
     @article{Tanstrum2012,
        author = {{Transtrum}, Mark K. and {Sethna}, James P.},
         title = "{Improvements to the Levenberg-Marquardt algorithm for nonlinear least-squares minimization}",
          year = 2012,
           doi = {10.48550/arXiv.1201.5885},
        adsurl = {https://ui.adsabs.harvard.edu/abs/2012arXiv1201.5885T},
     }
-    ```
+
 
     The damping factor $\\lambda$ is adjusted at each iteration:
     it is effectively increased when we are far from the solution, and

astrophot/fit/mala.py

@@ -23,12 +23,11 @@ class MALA(BaseOptimizer):
     Which can be found fairly easily with the LM optimizer (see the fitting
     methods tutorial).
 
-    **Args:**
-    -  `chains`: The number of MCMC chains to run in parallel. Default is 4.
-    -  `epsilon`: The step size for the MALA sampler. Default is 1e-2.
-    -  `mass_matrix`: The mass matrix for the MALA sampler. If None, the identity matrix is used.
-    -  `progress_bar`: Whether to show a progress bar during sampling. Default is True.
-    -  `likelihood`: The likelihood function to use for the MCMC sampling. Can be "gaussian" or "poisson". Default is "gaussian".
+    :param chains: The number of MCMC chains to run in parallel. Default is 4.
+    :param epsilon: The step size for the MALA sampler. Default is 1e-2.
+    :param mass_matrix: The mass matrix for the MALA sampler. If None, the identity matrix is used.
+    :param progress_bar: Whether to show a progress bar during sampling. Default is True.
+    :param likelihood: The likelihood function to use for the MCMC sampling. Can be "gaussian" or "poisson". Default is "gaussian".
     """
 
     def __init__(

astrophot/fit/mhmcmc.py

@@ -26,8 +26,7 @@ class MHMCMC(BaseOptimizer):
     number of parameters by default, but can be made higher (not lower) if desired.
     This is done by passing a 2D array of shape (nwalkers, ndim) to the `fit` method.
 
-    **Args:**
-    -  `likelihood`: The likelihood function to use for the MCMC sampling. Can be "gaussian" or "poisson". Default is "gaussian".
+    :param likelihood: The likelihood function to use for the MCMC sampling. Can be "gaussian" or "poisson". Default is "gaussian".
     """
 
     def __init__(

astrophot/fit/scipy_fit.py

@@ -19,11 +19,10 @@ class ScipyFit(BaseOptimizer):
     tasks. It supports a variety of methods, however only a subset allow users to
     define boundaries for the parameters. This wrapper is only for those methods.
 
-    **Args:**
-    -  `model`: The model to fit, which should be an instance of `Model`.
-    -  `initial_state`: Initial guess for the model parameters as a 1D tensor.
-    -  `method`: The optimization method to use. Default is "Nelder-Mead", but can be set to any of: "Nelder-Mead", "L-BFGS-B", "TNC", "SLSQP", "Powell", or "trust-constr".
-    -  `ndf`: Optional number of degrees of freedom for the fit. If not provided, it is calculated as the number of data points minus the number of parameters.
+    :param model: The model to fit, which should be an instance of `Model`.
+    :param initial_state: Initial guess for the model parameters as a 1D Array.
+    :param method: The optimization method to use. Default is "Nelder-Mead", but can be set to any of: "Nelder-Mead", "L-BFGS-B", "TNC", "SLSQP", "Powell", or "trust-constr".
+    :param ndf: Optional number of degrees of freedom for the fit. If not provided, it is calculated as the number of data points minus the number of parameters.
     """
 
     def __init__(

astrophot/image/cmos_image.py

@@ -5,12 +5,17 @@
 from .mixins import CMOSMixin
 from .model_image import ModelImage
 from ..backend_obj import backend
+from ..utils.decorators import combine_docstrings
 
+__all__ = ("CMOSModelImage", "CMOSTargetImage")
 
+
+@combine_docstrings
 class CMOSModelImage(CMOSMixin, ModelImage):
     """A ModelImage with CMOS-specific functionality."""
 
 
+@combine_docstrings
 class CMOSTargetImage(CMOSMixin, TargetImage):
     """
     A TargetImage with CMOS-specific functionality.