Add sphinx-gallery based plot gallery to docs

Add a gallery page with copy-able example code and rendered plots,
similar to matplotlib's plot_types page. Examples use real Visium
breast cancer tissue data alongside the synthetic blobs dataset.

Closes scverse/2026_04_hackathon_padua#20

Made-with: Cursor

Author: asarigun

.gitignore

@@ -22,6 +22,10 @@ __pycache__/
 # docs
 /docs/generated/
 /docs/_build/
+/docs/auto_gallery/
+/docs/sg_execution_times.rst
+/docs/gallery/**/data/
+/docs/gallery/**/__pycache__/
 
 # IDEs
 /.idea/

docs/conf.py

@@ -56,6 +56,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
+    "sphinx_gallery.gen_gallery",
     "sphinxcontrib.bibtex",
     "sphinxcontrib.katex",
     "sphinx_autodoc_typehints",
@@ -118,6 +119,9 @@
     "tutorials/notebooks/README.md",
     "tutorials/notebooks/references.md",
     "tutorials/notebooks/notebooks/paper_reproducibility/*",
+    "gallery",
+    "auto_gallery/**/*.ipynb",
+    "auto_gallery/**/*.py",
 ]
 
 
@@ -157,3 +161,18 @@
     # you can add an exception to this list.
     ("py:class", "igraph.Graph"),
 ]
+
+# -- Sphinx-Gallery configuration -------------------------------------------
+
+sys.path.insert(0, str(HERE / "gallery"))
+
+sphinx_gallery_conf = {
+    "examples_dirs": ["gallery"],
+    "gallery_dirs": ["auto_gallery"],
+    "filename_pattern": r"/plot_",
+    "ignore_pattern": r"(__init__|_helpers)\.py",
+    "image_scrapers": ("matplotlib",),
+    "matplotlib_animations": True,
+    "within_subsection_order": "FileNameSortKey",
+    "download_all_examples": True,
+}

docs/gallery/README.rst

@@ -0,0 +1,4 @@
+Gallery
+=======
+
+Examples demonstrating the plotting capabilities of ``spatialdata-plot``.

docs/gallery/_helpers.py

@@ -0,0 +1,60 @@
+"""Shared data loaders for gallery examples."""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+import scanpy as sc
+import spatialdata as sd
+from spatialdata.models import Image2DModel, ShapesModel, TableModel
+
+
+def load_visium_breast_cancer() -> sd.SpatialData:
+    """Load Visium breast cancer tissue as a SpatialData object.
+
+    Uses ``scanpy.datasets.visium_sge`` which caches the download
+    via :mod:`pooch`, so the data is only fetched once.
+    """
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        adata = sc.datasets.visium_sge(
+            sample_id="V1_Breast_Cancer_Block_A_Section_1",
+        )
+
+    sample = list(adata.uns["spatial"].keys())[0]
+    meta = adata.uns["spatial"][sample]
+    sf = meta["scalefactors"]["tissue_hires_scalef"]
+
+    image = Image2DModel.parse(
+        np.moveaxis(meta["images"]["hires"], -1, 0),
+        dims=("c", "y", "x"),
+    )
+
+    radius = meta["scalefactors"]["spot_diameter_fullres"] * sf / 2
+    circles = ShapesModel.parse(
+        adata.obsm["spatial"] * sf,
+        geometry=0,
+        radius=radius,
+        index=adata.obs_names,
+    )
+
+    adata.obs["region"] = "spots"
+    adata.obs["region"] = adata.obs["region"].astype("category")
+    adata.obs["instance_key"] = adata.obs_names
+    table = TableModel.parse(
+        adata,
+        region="spots",
+        region_key="region",
+        instance_key="instance_key",
+    )
+
+    table.var_names_make_unique()
+    sc.pp.normalize_total(table)
+    sc.pp.log1p(table)
+
+    return sd.SpatialData(
+        images={"tissue": image},
+        shapes={"spots": circles},
+        tables={"table": table},
+    )

docs/gallery/basic/README.rst

@@ -0,0 +1,4 @@
+Basic
+-----
+
+Rendering individual spatial element types.

docs/gallery/basic/plot_render_images.py

@@ -0,0 +1,14 @@
+"""
+Render tissue image
+===================
+
+Render an H&E tissue image from a Visium experiment.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+sdata.pl.render_images("tissue").pl.show()

docs/gallery/basic/plot_render_labels.py

@@ -0,0 +1,13 @@
+"""
+Render labels
+=============
+
+Render a cell segmentation mask.
+"""
+
+import spatialdata as sd
+import spatialdata_plot  # noqa: F401
+
+sdata = sd.datasets.blobs()
+
+sdata.pl.render_labels("blobs_labels").pl.show()

docs/gallery/basic/plot_render_points.py

@@ -0,0 +1,13 @@
+"""
+Render points
+=============
+
+Render transcript detections as points.
+"""
+
+import spatialdata as sd
+import spatialdata_plot  # noqa: F401
+
+sdata = sd.datasets.blobs()
+
+sdata.pl.render_points("blobs_points", size=3).pl.show()

docs/gallery/basic/plot_render_shapes.py

@@ -0,0 +1,14 @@
+"""
+Render spots
+============
+
+Render Visium spot shapes on their own.
+"""
+
+from _helpers import load_visium_breast_cancer
+
+import spatialdata_plot  # noqa: F401
+
+sdata = load_visium_breast_cancer()
+
+sdata.pl.render_shapes("spots").pl.show()

docs/gallery/customization/README.rst

@@ -0,0 +1,4 @@
+Customization
+-------------
+
+Styling options: colormaps, outlines, contours, and alpha.