Fix AstroPhot docstrings to explicit RST fields for Sphinx compatibility (#294)

Updates docstrings to RST for Sphinx/Jupyter Book compatibility, merges
docstrings across the MRO, and rebuilds the API docs structure with
autodoc pages and MathJax support.

## Changes Made
- Reworked `combine_docstrings` to merge parameters/options from the
full MRO into a single RST parameter list and add `[model param]` tags
to distinguish model parameters from options.
- Converted model and mixin docstrings from markdown to RST (including
`.. math::` blocks).
- Converted docstrings in the **image**, **fitting**, and **plotting**
sections to explicit RST field-list syntax using `:param:`, `:type:`,
`:returns:`, and `:rtype:` (replacing `Args:` / `Returns:` style
sections).
- Updated docstring terminology from `Tensor`/`tensor` to `Array` where
applicable, to reflect support for both PyTorch and JAX backends.
- Added `description` entries to every `_parameter_specs` parameter.
- Applied `combine_docstrings` to auto-generated classes in `radial.py`
and `radial_psf.py`.
- Removed `make_docs.py` and replaced the docstring notebook tree with
Sphinx autodoc RST pages.

## Documentation
- Added `docs/source/astrophotdocs/*.rst` autodoc pages and updated
`astrophotdocs/index.rst`.
- Enabled MathJax in the Jupyter Book/Sphinx configuration.

## Testing
- Targeted pytest runs for utility and parameter tests.
- Targeted pytest runs for updated sections: `tests/test_image.py`,
`tests/test_fit.py`, and `tests/test_plots.py`.

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>

> 
> ----
> 
> *This section details on the original issue you should resolve*
> 
> <issue_title>Model docstrings need a rewrite</issue_title>
> <issue_description>As part of my latest update I tried to make the
model docstrings use markdown formatting, but this ultimately doesn't
seem to have worked. I would like to revert to a format that sphinx
autodoc can work with (I think this is RST). My main challenge is to get
it to work in a way that also compiles into the jupyter-book website
system with latex equations.
> 
> Also, I think the `combine_docstrings` decorator should be smarter
about merging docstrings. It should find all of the "Parameters" and the
"Options" from each collected docstring and merge them into single lists
so that autodoc compiles them correctly.
> 
> The combine_docstrings decorator also needs to be applied to all the
auto generated types in the `radial.py` and `radial_psf.py` files.
Further, they should be modified so that sphinx autodoc picks them up
when generating the documentation.
> 
> My attempted giant jupyter notebook of docstrings didn't work so that
should be removed and instead the tree of autodoc results should be made
more human navigable.
> 
> While doing this, it would be good to also check that all the
docstrings are up to date to match the actual coded implementations. And
the "Parameters" descriptions in the docstrings should be added as a
"description" key in all the `_parameter_specs` dictionaries associated
with each model.</issue_description>
> 
> ## Comments on the Issue (you are @copilot in this section)
> 
> <comments>
> </comments>
> 


</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #293

<!-- START COPILOT CODING AGENT TIPS -->
---

⌨️ Start Copilot coding agent tasks without leaving your editor —
available in [VS Code](https://gh.io/cca-vs-code-docs), [Visual
Studio](https://gh.io/cca-visual-studio-docs), [JetBrains
IDEs](https://gh.io/cca-jetbrains-docs) and
[Eclipse](https://gh.io/cca-eclipse-docs).

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: ConnorStoneAstro <78555321+ConnorStoneAstro@users.noreply.github.com>
Co-authored-by: Connor Stone <connorstone628@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 4 people

.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.