Sphinx documentation (#226)

* chore: add docs optional-dependency group to pyproject.toml

Add sphinx, furo, and sphinx-design as an optional 'docs' extra so the
documentation dependencies are declared alongside the project:

    uv sync --extra docs

Co-authored-by: GitHub Copilot <copilot@github.com>

* docs: add Sphinx configuration, custom extension, and static assets

- conf.py: configure furo theme, autodoc, napoleon (Google style), and
  sphinx-design; extension load order ensures galsim_docstring runs
  before napoleon so the injected Parameters block is handled correctly
- Makefile: 'make html' and 'make clean' targets using 'uv run'
- requirements.txt: standalone pip-installable docs deps
- _ext/galsim_docstring.py: autodoc-process-docstring hook that splits
  docstrings produced by the @implements decorator.  It:
    * extracts the GalSim Parameters block and re-injects it in Google
      style so napoleon renders it as an explicit parameter table
    * wraps the remaining original GalSim narrative in a sphinx-design
      dropdown so it is collapsible in the HTML output
- _static/custom.css: visual tweaks for the dropdown and parameter lists

Co-authored-by: GitHub Copilot <copilot@github.com>

* docs: add index page and API reference RST sources

- index.rst: landing page with a grid linking to the API reference and
  the upstream GalSim docs
- api/index.rst: top-level API table of contents
- api/gsobjects.rst: GSObject base class and all analytic profiles
  (Gaussian, Moffat, Exponential, Spergel, Box, Pixel, DeltaFunction,
  Sum, Convolution, Deconvolution, Transform, Shear)
- api/image.rst: Image variants, Bounds, and Position classes
- api/noise.rst: random deviates, noise models, PhotonArray, Sensor
- api/wcs.rst: WCS classes, CelestialCoord, Angle, FitsHeader
- api/interpolation.rst: interpolant classes and InterpolatedImage
- api/core.rst: internal utility modules (utils, math, integrate,
  interpolate, draw)

Co-authored-by: GitHub Copilot <copilot@github.com>

* style: format pyproject toml

* docs: fix docstrings so they follow rst syntax and galsim style

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: GitHub Copilot <copilot@github.com>

* docs: add sharp bits block to emphasize classes that have a LAX description which is usually very important

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: GitHub Copilot <copilot@github.com>

* ci: add make docs workflow

Co-authored-by: GitHub Copilot <copilot@github.com>

* docs: interpolated image before interpolatns

* docs: small clarification

* docs: not needed

* style: formatting

* docs: add user-facing guide pages (installation, quickstart, notable-differences, api-coverage)

- installation.rst: pip/GPU/dev install instructions, test and lint commands
- quickstart.rst: complete simulation walkthrough with jit, grad, and vmap examples
- notable-differences.rst: covers immutability, array views, PRNG, PyTrees,
  tracing restrictions, profile limitations, numerical precision, and @implements
- api-coverage.rst: current 22.5% coverage summary with collapsible full API list

--trailer "Co-authored-by: GitHub Copilot <copilot@github.com>"

* docs: expand index page and reorganise core API page

- index.rst: merged content from mkdown/index.md — added CI/Ruff/pre-commit
  badges, early-dev warning admonition, Why JAX-GalSim feature grid, quick
  install block, minimal JIT+grad example, and expanded navigation card grid;
  toctree now includes the four new guide pages
- core.rst: split into labelled sections (Math, Drawing, Utilities) and moved
  core.utils to the bottom so implementation details appear after higher-level
  modules

--trailer "Co-authored-by: GitHub Copilot <copilot@github.com>"

* docs: rst fix indentation

* docs: fix rst indentation

* docs: add Read the Docs configuration file

Co-authored-by: GitHub Copilot <copilot@github.com>

* Trigger RTD Build

* docs: fix some rst synxtax errors (single ticks, bullet indentation)

Co-authored-by: GitHub Copilot <copilot@github.com>

Co-authored-by: Copilot <copilot@github.com>

* docs: github action not needed since we are using RTD now

* docs: use sharp bits instead of notable-difefrences

* docs: use sharp bits

* docs: note about core not intended for public usage

* docs: changes suggested by Matt to align more with GalSim

* docs: add documentation link to readme

Co-authored-by: Copilot <copilot@github.com>

* docs: small correction

* Apply suggestion from @beckermr

* Apply suggestion from @beckermr

* docs: added versioning and API policy

* docs: title underlin too short

* docs: forgot this note

* Apply suggestion from @beckermr

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Apply suggestion from @beckermr

---------

Co-authored-by: GitHub Copilot <copilot@github.com>
Co-authored-by: Matthew R. Becker <beckermr@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 4 people

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs configuration
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  commands:
+    - pip install uv
+    - uv sync --extra docs
+    - uv run sphinx-build -b html docs $READTHEDOCS_OUTPUT/html
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false

README.md

@@ -2,10 +2,13 @@
 
 **JAX port of GalSim, for parallelized, GPU accelerated, and differentiable galaxy image simulations.**
 
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) [![Python package](https://github.com/GalSim-developers/JAX-GalSim/actions/workflows/python_package.yaml/badge.svg)](https://github.com/GalSim-developers/JAX-GalSim/actions/workflows/python_package.yaml) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/GalSim-developers/JAX-GalSim/main.svg)](https://results.pre-commit.ci/latest/github/GalSim-developers/JAX-GalSim/main) [![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/GalSim-developers/JAX-GalSim)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) [![Python package](https://github.com/GalSim-developers/JAX-GalSim/actions/workflows/python_package.yaml/badge.svg)](https://github.com/GalSim-developers/JAX-GalSim/actions/workflows/python_package.yaml) [![Documentation Status](https://readthedocs.org/projects/jax-galsim/badge/?version=latest)](https://jax-galsim.readthedocs.io/en/latest/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/GalSim-developers/JAX-GalSim/main.svg)](https://results.pre-commit.ci/latest/github/GalSim-developers/JAX-GalSim/main) [![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/GalSim-developers/JAX-GalSim)
 
 **Disclaimer**: This project is still in an early development phase, **please use the [reference GalSim implementation](https://github.com/GalSim-developers/GalSim) for any scientific applications.**
 
+**You can find the most up-to-date documentation for the project [here](https://jax-galsim.readthedocs.io/en/latest).**
+
+
 ## Objective and Design
 
 The goal of this library is to reimplement GalSim functionalities in pure JAX to allow for automatic differentiation, GPU acceleration, and batched computations.
@@ -44,124 +47,4 @@ about the inner workings of GalSim and how to code in JAX.
 
 ## Current GalSim API Coverage
 
-<!-- start-api-coverage -->
-JAX-GalSim has implemented 22.5% of the GalSim API. See the list below for the supported APIs.
-
-<details>
-
-- galsim.Add
-- galsim.AffineTransform
-- galsim.Angle
-- galsim.AngleUnit
-- galsim.BaseDeviate
-- galsim.BaseNoise
-- galsim.BaseWCS
-- galsim.BinomialDeviate
-- galsim.Bounds
-- galsim.BoundsD
-- galsim.BoundsI
-- galsim.Box
-- galsim.CCDNoise
-- galsim.CelestialCoord
-- galsim.Chi2Deviate
-- galsim.Convolution
-- galsim.Convolve
-- galsim.Cubic
-- galsim.Deconvolution
-- galsim.Deconvolve
-- galsim.Delta
-- galsim.DeltaFunction
-- galsim.DeviateNoise
-- galsim.Exponential
-- galsim.FitsHeader
-- galsim.FitsWCS
-- galsim.GSFitsWCS
-- galsim.GSObject
-- galsim.GSParams
-- galsim.GalSimBoundsError
-- galsim.GalSimConfigError
-- galsim.GalSimConfigValueError
-- galsim.GalSimDeprecationWarning
-- galsim.GalSimError
-- galsim.GalSimFFTSizeError
-- galsim.GalSimHSMError
-- galsim.GalSimImmutableError
-- galsim.GalSimIncompatibleValuesError
-- galsim.GalSimIndexError
-- galsim.GalSimKeyError
-- galsim.GalSimNotImplementedError
-- galsim.GalSimRangeError
-- galsim.GalSimSEDError
-- galsim.GalSimUndefinedBoundsError
-- galsim.GalSimValueError
-- galsim.GalSimWarning
-- galsim.GammaDeviate
-- galsim.Gaussian
-- galsim.GaussianDeviate
-- galsim.GaussianNoise
-- galsim.Image
-- galsim.ImageCD
-- galsim.ImageCF
-- galsim.ImageD
-- galsim.ImageF
-- galsim.ImageI
-- galsim.ImageS
-- galsim.ImageUI
-- galsim.ImageUS
-- galsim.Interpolant
-- galsim.InterpolatedImage
-- galsim.JacobianWCS
-- galsim.Lanczos
-- galsim.Linear
-- galsim.Moffat
-- galsim.Nearest
-- galsim.OffsetShearWCS
-- galsim.OffsetWCS
-- galsim.PhotonArray
-- galsim.Pixel
-- galsim.PixelScale
-- galsim.PoissonDeviate
-- galsim.PoissonNoise
-- galsim.Position
-- galsim.PositionD
-- galsim.PositionI
-- galsim.Quintic
-- galsim.Sensor
-- galsim.Shear
-- galsim.ShearWCS
-- galsim.SincInterpolant
-- galsim.Spergel
-- galsim.Sum
-- galsim.TanWCS
-- galsim.Transform
-- galsim.Transformation
-- galsim.UniformDeviate
-- galsim.VariableGaussianNoise
-- galsim.WeibullDeviate
-- galsim.bessel.j0
-- galsim.bessel.kv
-- galsim.bessel.si
-- galsim.fits.closeHDUList
-- galsim.fits.readCube
-- galsim.fits.readFile
-- galsim.fits.readMulti
-- galsim.fits.write
-- galsim.fits.writeFile
-- galsim.fitswcs.CelestialWCS
-- galsim.integ.int1d
-- galsim.noise.addNoise
-- galsim.noise.addNoiseSNR
-- galsim.random.permute
-- galsim.utilities.g1g2_to_e1e2
-- galsim.utilities.horner
-- galsim.utilities.printoptions
-- galsim.utilities.unweighted_moments
-- galsim.utilities.unweighted_shape
-- galsim.wcs.EuclideanWCS
-- galsim.wcs.LocalWCS
-- galsim.wcs.UniformWCS
-
-</details>
-<!-- end-api-coverage -->
-
-_**Note**: The coverage list is generated automatically by the `scripts/update_api_coverage.py` script. To update it, run `python scripts/update_api_coverage.py` from the root of the repository._
+JAX-GalSim current has implemented **22.5%** of the GalSim API. See the corresponding [documentation page](https://jax-galsim.readthedocs.io/en/latest/api-coverage) for a list of what is currently implemented.

docs/Makefile

@@ -0,0 +1,24 @@
+# Minimal Sphinx Makefile — uses uv run so all package deps are always available.
+
+SPHINXBUILD  = uv run sphinx-build
+SOURCEDIR    = .
+BUILDDIR     = _build
+
+.PHONY: help html clean livehtml
+
+help:
+	@echo "Usage:"
+	@echo "  make html      Build the HTML documentation"
+	@echo "  make clean     Remove the build directory"
+	@echo "  make livehtml  Auto-rebuild on file changes (requires sphinx-autobuild)"
+
+html:
+	$(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html
+
+clean:
+	rm -rf $(BUILDDIR)
+
+livehtml:
+	uv run sphinx-autobuild $(SOURCEDIR) $(BUILDDIR)/html \
+		--ignore "**/_build/**" \
+		--ignore "**/.DS_Store"