Sphinx documentation by ismael-mendoza · Pull Request #226 · GalSim-developers/JAX-GalSim

ismael-mendoza · 2026-04-30T22:18:34Z

It ended up being simpler using sphinx and rst rather than markdown because we are ingesting the GalSim docstrings. This PR supersedes #204

There are also small scattered changes to some existing jax-galsim docstrings to make sure they follow the galsim docstring format and the correct rst syntax.

Suggestions welcome! the build looks good in my computer and haven't been able to find major issues with the API reference

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>

@implements

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

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

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

…iption which is usually very important Co-authored-by: Copilot <copilot@github.com> Co-authored-by: GitHub Copilot <copilot@github.com>

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

@implements

…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>"

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

codspeed-hq · 2026-04-30T22:39:01Z

Merging this PR will improve performance by ×2

⚠️

Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️

Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 9 improved benchmarks
✅ 27 untouched benchmarks

Performance Changes

	Mode	Benchmark	`BASE`	`HEAD`	Efficiency
⚡	WallTime	`test_benchmark_spergel_calcfluxrad[run]`	215.4 µs	137.9 µs	+56.25%
⚡	WallTime	`test_benchmarks_lanczos_interp[xval-no_conserve_dc-run]`	115.9 µs	68.9 µs	+68.32%
⚡	WallTime	`test_benchmarks_lanczos_interp[xval-conserve_dc-run]`	132.4 µs	65.8 µs	×2
⚡	WallTime	`test_benchmark_invert_ab_noraise[run]`	143.8 µs	79.3 µs	+81.28%
⚡	WallTime	`test_benchmarks_lanczos_interp[kval-conserve_dc-run]`	55.1 µs	30.6 µs	+79.83%
⚡	WallTime	`test_benchmarks_lanczos_interp[kval-no_conserve_dc-run]`	50.9 µs	30.7 µs	+65.7%
⚡	WallTime	`test_benchmark_interpimage_flux_frac[run]`	431.6 µs	252.5 µs	+70.95%
⚡	WallTime	`test_benchmark_spergel_kvalue[run]`	11.5 ms	8.7 ms	+32.93%
⚡	WallTime	`test_benchmark_moffat_init[run]`	94.8 µs	46.7 µs	×2

_{Comparing sphinx-docs (60ec3fa) with main (f04b831)}

beckermr · 2026-04-30T22:41:04Z

Can we add a build on readthedocs or github pages or something so that we can preview changes?

beckermr · 2026-04-30T22:54:04Z

I requested RTD for this repo.

ismael-mendoza · 2026-05-01T12:35:58Z

ah yes I can do that, although I was planning on using github pages. Perhaps we can discuss if RTD is better during the meeting? (it requires some additional setup i believe)

ismael-mendoza · 2026-05-01T12:39:27Z

actually RTD could be nice so we can preview the PR, github only allows one page per repo if I understand correctly. let me try to configure that...

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

ismael-mendoza · 2026-05-01T12:51:35Z

@beckermr it's available now! you just need to click on the RTD build below

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

beckermr

I left some general comments. Overall, this looks great!

beckermr · 2026-05-01T13:42:30Z

We should also add a link to the RTD site to the repo readme.

beckermr · 2026-05-01T13:53:10Z

We also need to add text on the versioning scheme. We settled on CalVer (https://calver.org/) with YYYY.MM.MICRO with MICRO resetting to 0 at the start of each month.

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

ismael-mendoza · 2026-05-01T18:32:16Z

@beckermr I think this is ready for another look!

I can think of automating the api coverage in a future PR...

beckermr · 2026-05-01T20:21:38Z

pre-commit.ci autofix

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

ismael-mendoza and others added 16 commits April 30, 2026 17:43

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

af2445f

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>

style: format pyproject toml

4e8f7cf

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

9b42963

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 descr…

a99ab72

…iption 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

8a6a6aa

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

docs: interpolated image before interpolatns

c4362d0

docs: small clarification

ad10f15

docs: not needed

67d16ac

style: formatting

5f9d152

Merge branch 'main' into sphinx-docs

62ec648

docs: rst fix indentation

2c94f2c

docs: fix rst indentation

e6f7d9c

ismael-mendoza and others added 2 commits May 1, 2026 08:43

docs: add Read the Docs configuration file

85d852c

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

Trigger RTD Build

9f1cf34

ismael-mendoza and others added 2 commits May 1, 2026 09:04

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

f1be2e8

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

c806cfa

beckermr requested changes May 1, 2026

View reviewed changes

ismael-mendoza mentioned this pull request May 1, 2026

WIP: Add documentation site with Material for MkDocs #204

Closed

ismael-mendoza and others added 6 commits May 1, 2026 13:24

docs: use sharp bits instead of notable-difefrences

470de0d

docs: use sharp bits

4d0290f

docs: note about core not intended for public usage

0b54c17

docs: changes suggested by Matt to align more with GalSim

535a3ac

docs: add documentation link to readme

f4b2832

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

docs: small correction

64fc07c

beckermr reviewed May 1, 2026

View reviewed changes

Comment thread docs/index.rst Outdated

Apply suggestion from @beckermr

45cd3b8

beckermr reviewed May 1, 2026

View reviewed changes

Comment thread docs/sharp-bits.rst Outdated

Apply suggestion from @beckermr

5c9a2e1

ismael-mendoza marked this pull request as ready for review May 1, 2026 18:27

ismael-mendoza added 3 commits May 1, 2026 14:28

docs: added versioning and API policy

cb1ca94

docs: title underlin too short

9399bda

docs: forgot this note

5a134bc

ismael-mendoza requested a review from beckermr May 1, 2026 18:32

beckermr reviewed May 1, 2026

View reviewed changes

Comment thread docs/_ext/galsim_docstring.py Outdated

Apply suggestion from @beckermr

fcf2b25

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

06344b8

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

beckermr reviewed May 1, 2026

View reviewed changes

Comment thread docs/sharp-bits.rst Outdated

Apply suggestion from @beckermr

60ec3fa

beckermr approved these changes May 1, 2026

View reviewed changes

beckermr enabled auto-merge (squash) May 1, 2026 20:31

beckermr merged commit 44aa3f6 into main May 1, 2026
9 checks passed

beckermr deleted the sphinx-docs branch May 1, 2026 20:35

beckermr mentioned this pull request May 1, 2026

Setup documentation system to keep track of implemented API #17

Closed

Conversation

ismael-mendoza commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will improve performance by ×2

Performance Changes

Uh oh!

beckermr commented Apr 30, 2026

Uh oh!

beckermr commented Apr 30, 2026

Uh oh!

ismael-mendoza commented May 1, 2026

Uh oh!

ismael-mendoza commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ismael-mendoza commented May 1, 2026

Uh oh!

beckermr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

beckermr commented May 1, 2026

Uh oh!

beckermr commented May 1, 2026

Uh oh!

Uh oh!

Uh oh!

ismael-mendoza commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

beckermr commented May 1, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ismael-mendoza commented Apr 30, 2026 •

edited

Loading

codspeed-hq Bot commented Apr 30, 2026 •

edited

Loading

ismael-mendoza commented May 1, 2026 •

edited

Loading

ismael-mendoza commented May 1, 2026 •

edited

Loading