WIP: Add documentation site with Material for MkDocs

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build documentation
+        if: github.event_name == 'pull_request'
+        run: mkdocs build --strict
+
+      - name: Deploy documentation
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: mkdocs gh-deploy --force

docs/api-coverage.md

@@ -0,0 +1,128 @@
+# API Coverage
+
+JAX-GalSim has implemented **22.5%** of the GalSim API. The project focuses on
+the most commonly used profiles and operations, with coverage expanding over time.
+
+## Supported APIs
+
+??? note "Click to expand the full list of implemented APIs"
+
+    - `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`
+
+## Updating Coverage
+
+```bash
+python scripts/update_api_coverage.py
+```
+
+Compares GalSim's public API against `jax_galsim`'s implementations and updates the coverage percentage and list in `README.md`.

docs/api/composition/convolve.md

@@ -0,0 +1,7 @@
+# Convolution & Deconvolution
+
+Convolve profiles together (e.g., galaxy with PSF) or deconvolve.
+
+::: jax_galsim.convolve.Convolution
+
+::: jax_galsim.convolve.Deconvolution

docs/api/composition/sum.md

@@ -0,0 +1,5 @@
+# Sum (Add)
+
+Add surface brightness profiles together.
+
+::: jax_galsim.sum.Sum

docs/api/composition/transform.md

@@ -0,0 +1,5 @@
+# Transform & Transformation
+
+Affine transformations of surface brightness profiles (shear, shift, rotation, flux scaling).
+
+::: jax_galsim.transform.Transformation

docs/api/config/errors.md

@@ -0,0 +1,5 @@
+# Errors & Warnings
+
+Exception and warning classes for JAX-GalSim error handling.
+
+::: jax_galsim.errors

docs/api/config/gsparams.md

@@ -0,0 +1,5 @@
+# GSParams
+
+Numerical configuration parameters controlling accuracy and performance trade-offs.
+
+::: jax_galsim.gsparams.GSParams

docs/api/config/utilities.md

@@ -0,0 +1,5 @@
+# Utilities
+
+General utility functions.
+
+::: jax_galsim.utilities

docs/api/coordinates/angle.md

@@ -0,0 +1,7 @@
+# Angle & AngleUnit
+
+Angle representation and unit conversion (radians, degrees, arcminutes, arcseconds, hours).
+
+::: jax_galsim.angle.Angle
+
+::: jax_galsim.angle.AngleUnit

docs/api/coordinates/bounds.md

@@ -0,0 +1,7 @@
+# Bounds
+
+Rectangular bounding box types for real-valued (`BoundsD`) and integer (`BoundsI`) coordinates.
+
+::: jax_galsim.bounds.BoundsD
+
+::: jax_galsim.bounds.BoundsI

docs/api/coordinates/celestial.md

@@ -0,0 +1,5 @@
+# CelestialCoord
+
+Celestial coordinate (RA, Dec) representation and operations.
+
+::: jax_galsim.celestial.CelestialCoord

docs/api/coordinates/position.md

@@ -0,0 +1,7 @@
+# Position
+
+2D position types for real-valued (`PositionD`) and integer (`PositionI`) coordinates.
+
+::: jax_galsim.position.PositionD
+
+::: jax_galsim.position.PositionI

docs/api/coordinates/shear.md

@@ -0,0 +1,5 @@
+# Shear
+
+Gravitational shear representation with multiple parametrizations (g1/g2, e1/e2, eta1/eta2).
+
+::: jax_galsim.shear.Shear

docs/api/core/draw.md

@@ -0,0 +1,5 @@
+# Core: Drawing
+
+Internal drawing utilities for rendering profiles to pixel grids.
+
+::: jax_galsim.core.draw

docs/api/core/interpolate.md

@@ -0,0 +1,5 @@
+# Core: Interpolation
+
+Internal interpolation utilities (Akima splines, coefficient computation).
+
+::: jax_galsim.core.interpolate

docs/api/core/math.md

@@ -0,0 +1,5 @@
+# Core: Math
+
+Gradient-safe mathematical utilities (`safe_sqrt`, etc.).
+
+::: jax_galsim.core.math

docs/api/core/utils.md

@@ -0,0 +1,5 @@
+# Core: Utilities
+
+Core utilities: `@implements` decorator, `has_tracers()`, type casting helpers.
+
+::: jax_galsim.core.utils

docs/api/image.md

@@ -0,0 +1,5 @@
+# Image
+
+Immutable JAX array wrapper with WCS and bounds metadata.
+
+::: jax_galsim.image.Image

docs/api/interpolation/interpolant.md

@@ -0,0 +1,17 @@
+# Interpolants
+
+Interpolation kernels for image resampling.
+
+::: jax_galsim.interpolant.Interpolant
+
+::: jax_galsim.interpolant.Nearest
+
+::: jax_galsim.interpolant.SincInterpolant
+
+::: jax_galsim.interpolant.Linear
+
+::: jax_galsim.interpolant.Cubic
+
+::: jax_galsim.interpolant.Quintic
+
+::: jax_galsim.interpolant.Lanczos

docs/api/interpolation/interpolatedimage.md

@@ -0,0 +1,5 @@
+# InterpolatedImage
+
+Surface brightness profile defined by interpolation over a given image.
+
+::: jax_galsim.interpolatedimage.InterpolatedImage

docs/api/math/bessel.md

@@ -0,0 +1,5 @@
+# Bessel Functions
+
+Bessel and related special functions.
+
+::: jax_galsim.bessel

docs/api/math/integ.md

@@ -0,0 +1,5 @@
+# Integration
+
+Numerical integration utilities.
+
+::: jax_galsim.integ

docs/api/noise/noise.md

@@ -0,0 +1,15 @@
+# Noise Models
+
+Noise classes for adding realistic noise to images.
+
+::: jax_galsim.noise.BaseNoise
+
+::: jax_galsim.noise.GaussianNoise
+
+::: jax_galsim.noise.PoissonNoise
+
+::: jax_galsim.noise.CCDNoise
+
+::: jax_galsim.noise.DeviateNoise
+
+::: jax_galsim.noise.VariableGaussianNoise

docs/api/noise/random.md

@@ -0,0 +1,19 @@
+# Random Deviates
+
+Random number generators.
+
+::: jax_galsim.random.BaseDeviate
+
+::: jax_galsim.random.UniformDeviate
+
+::: jax_galsim.random.GaussianDeviate
+
+::: jax_galsim.random.PoissonDeviate
+
+::: jax_galsim.random.Chi2Deviate
+
+::: jax_galsim.random.GammaDeviate
+
+::: jax_galsim.random.WeibullDeviate
+
+::: jax_galsim.random.BinomialDeviate

docs/api/photons/photon_array.md

@@ -0,0 +1,5 @@
+# PhotonArray
+
+Array of photon positions, fluxes, and other properties for photon shooting.
+
+::: jax_galsim.photon_array.PhotonArray

docs/api/photons/sensor.md

@@ -0,0 +1,5 @@
+# Sensor
+
+Sensor model for converting photons to pixel counts.
+
+::: jax_galsim.sensor.Sensor

docs/api/profiles/box.md

@@ -0,0 +1,7 @@
+# Box & Pixel
+
+Box (uniform rectangular) and Pixel (unit-width box) surface brightness profiles.
+
+::: jax_galsim.box.Box
+
+::: jax_galsim.box.Pixel

docs/api/profiles/deltafunction.md

@@ -0,0 +1,5 @@
+# DeltaFunction
+
+Delta function (point source) surface brightness profile.
+
+::: jax_galsim.deltafunction.DeltaFunction

docs/api/profiles/exponential.md

@@ -0,0 +1,5 @@
+# Exponential
+
+Exponential surface brightness profile, commonly used for galaxy disk components.
+
+::: jax_galsim.exponential.Exponential

docs/api/profiles/gaussian.md

@@ -0,0 +1,5 @@
+# Gaussian
+
+Circular or elliptical Gaussian surface brightness profile.
+
+::: jax_galsim.gaussian.Gaussian

docs/api/profiles/gsobject.md

@@ -0,0 +1,5 @@
+# GSObject
+
+Base class for all surface brightness profiles.
+
+::: jax_galsim.gsobject.GSObject

docs/api/profiles/moffat.md

@@ -0,0 +1,5 @@
+# Moffat
+
+Moffat surface brightness profile, commonly used for PSF modeling.
+
+::: jax_galsim.moffat.Moffat

docs/api/profiles/spergel.md

@@ -0,0 +1,5 @@
+# Spergel
+
+Spergel surface brightness profile, a flexible model for galaxy light distributions.
+
+::: jax_galsim.spergel.Spergel