WIP: Add documentation site with Material for MkDocs#204
Draft
Conversation
Set up full documentation infrastructure with auto-generated API reference from docstrings, narrative guides, and GitHub Pages deployment via CI. - Add mkdocs-material and mkdocstrings[python] as docs dependencies - Create mkdocs.yml with Material theme, left sidebar nav, Mermaid, MathJax - Add narrative pages: home, getting started, architecture, notable differences - Add API reference stubs for all public modules targeting specific classes - Add GitHub Actions workflow for build on PR / deploy on push to main Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove duplicated explanations, tighten prose, and condense sections that repeated information already covered on other pages. Net reduction of ~80 lines with no content loss -- cross-links replace duplication. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove the architecture/ pages (pytree, implements, gsobject, drawing) and key-concepts page. Consolidate their most useful content into notable-differences.md, which now thoroughly covers immutability, array views, RNG, PyTree registration, control flow/tracing, profile restrictions, numerical precision, and the @implements decorator. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EiffL
changed the title
Merging this PR will improve performance by 34.54%
|
| Mode | Benchmark | BASE |
HEAD |
Efficiency | |
|---|---|---|---|---|---|
| ⚡ | Simulation | test_benchmark_interpimage_flux_frac[run] |
2.2 ms | 1.6 ms | +34.54% |
Comparing documentation (75f9767) with main (ef2c37a)
beckermr
reviewed
Feb 20, 2026
|
|
||
| ## Supported APIs | ||
|
|
||
| ??? note "Click to expand the full list of implemented APIs" |
Collaborator
There was a problem hiding this comment.
Is this AI slop or actual markdown.
Collaborator
There was a problem hiding this comment.
I think it's actually syntax from the admonition plugin? https://squidfunk.github.io/mkdocs-material/reference/admonitions/#collapsible-blocks
ismael-mendoza
requested changes
Mar 4, 2026
Collaborator
ismael-mendoza
left a comment
ismael-mendoza
left a comment
There was a problem hiding this comment.
I flagged a couple of cases in the examples provided that don't actually work. @EiffL could you modify as needed?
Comment on lines
+42
to
+54
| ```python | ||
| import jax | ||
|
|
||
| @jax.jit | ||
| def simulate(flux, sigma): | ||
| gal = jax_galsim.Gaussian(flux=flux, sigma=sigma) | ||
| psf = jax_galsim.Gaussian(flux=1.0, sigma=1.0) | ||
| final = jax_galsim.Convolve([gal, psf]) | ||
| return final.drawImage(scale=0.2) | ||
|
|
||
| # First call compiles; subsequent calls are fast | ||
| image = simulate(1e5, 2.0) | ||
| ``` |
Collaborator
There was a problem hiding this comment.
this does not work without setting the gsparams with fft_size and specifying the size of the image to draw
Comment on lines
+79
to
+93
| ```python | ||
| import jax.numpy as jnp | ||
|
|
||
| sigmas = jnp.linspace(1.0, 4.0, 10) | ||
|
|
||
| @jax.vmap | ||
| def batch_simulate(sigma): | ||
| gal = jax_galsim.Gaussian(flux=1e5, sigma=sigma) | ||
| psf = jax_galsim.Gaussian(flux=1.0, sigma=1.0) | ||
| final = jax_galsim.Convolve([gal, psf]) | ||
| return final.drawImage(scale=0.2, nx=64, ny=64).array | ||
|
|
||
| # Simulate all 10 galaxies in parallel | ||
| images = batch_simulate(sigmas) # shape: (10, 64, 64) | ||
| ``` |
Collaborator
There was a problem hiding this comment.
this example also requires specifying the gsparams
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
What's included
jit/grad/vmapexamples@implementsdecorator.github/workflows/docs.yml):mkdocs build --stricton PRs,mkdocs gh-deployon push to mainKnown limitations
@implementsdecorator copies GalSim's docstrings at runtime, but mkdocstrings doesn't always pick them up cleanly. RST cross-references (:func:,:class:) from GalSim's docstrings render as literal text rather than links.🤖 Generated with Claude Code