Contributing

Thanks for contributing a notebook to the spatialdata-plot gallery.

Setup

git clone https://github.com/scverse/spatialdata-plot-notebooks.git
cd spatialdata-plot-notebooks
pip install -e ".[exec,dev]"
pre-commit install

Decide the type:
- tutorials/<topic>.ipynb — end-to-end workflow on a real dataset (Visium, Xenium, MERFISH, …). Focuses on a complete analysis story.
- examples/<group>/<topic>.ipynb — short, single-feature notebook (e.g., examples/customization/outlines.ipynb). Focuses on one technique.
Start the notebook with a markdown cell containing:
- A title (# ...).
- 2-3 sentences on what the reader will learn.
- A dataset citation when applicable.
Use squidpy.datasets.* or spatialdata.datasets.* for data — never raw URLs. Both libraries cache via pooch, so first-run downloads are cheap on re-runs.
Re-execute the notebook end-to-end (Restart Kernel & Run All) and commit with outputs. The spatialdata-plot docs build performs no execution; what you commit is what users see rendered.
Add the notebook to the appropriate index.md so it appears in the gallery toctree.
Place the gallery thumbnail and any other media (GIFs, screenshots, static PNGs referenced from the notebook) under _static/img/. Reference them from index.md and notebook markdown cells with relative paths (e.g. :img-top: ../_static/img/<slug>.png from inside examples/ or tutorials/, and ![…](../_static/img/<slug>.gif) from a notebook cell). Do not drop assets next to the notebook itself.
Open a PR. CI will:
- Lint structure and code (lint.yaml).
- Re-execute the notebook against the latest spatialdata-plot release and diff outputs (execute.yaml).

Edit, re-execute, commit. CI catches output drift on the next scheduled run if you forget.

Raw datasets (use squidpy.datasets / spatialdata.datasets).
Notebooks larger than ~5 MB after execution — open an issue first; we may need git-lfs or a downsampled variant.
Cells that depend on local files outside the repo.

Open an issue or ping in scverse Zulip.