Auto-pull notebooks main, add card gallery, link from README

C2 — Render notebooks-repo main, not the pinned SHA
   .readthedocs.yaml gains a `post_checkout` job that runs
   `git submodule update --init --remote --recursive` so RTD always renders
   the latest gallery without requiring a submodule-bump PR here. Mirrored
   in the docs CI job in build.yaml. Trade-off: docs at older lib tags are
   no longer bit-for-bit reproducible for the gallery.

N1 — Card gallery with thumbnails (matches scverse/spatialdata)
   Add sphinx-design to doc deps and to the extension list. Rewrite
   gallery.md to use {grid}/{grid-item-card} with an :img-top: thumbnail.
   Thumbnail PNG (getting_started.png) committed under docs/_static/gallery.

N6 — README points at the gallery
   New `link-gallery` link target alongside the existing API reference;
   existing spatialdata-notebooks link reframed as a "broader analyses"
   pointer. Fixes the "Visiualizations" typo while there.

Author: timtreis

.github/workflows/build.yaml

@@ -32,6 +32,9 @@ jobs:
         with:
           submodules: true
           fetch-depth: 0
+      - name: Pull latest notebooks
+        # Match RTD: render whatever is on notebooks-repo main, not the pinned SHA.
+        run: git submodule update --init --remote --recursive
       - name: Install uv
         uses: astral-sh/setup-uv@v7
       - name: Build docs

.readthedocs.yaml

@@ -6,6 +6,12 @@ build:
     python: "3.13"
     nodejs: latest
   jobs:
+    post_checkout:
+      # Always render the latest notebooks-repo main, not the SHA pinned in
+      # this repo's index. Trade-off: docs at older lib tags are not bit-for-bit
+      # reproducible for the gallery — a re-build shows whatever the notebooks
+      # repo's main looked like at build time.
+      - git submodule update --init --remote --recursive
     create_environment:
       - asdf plugin add uv
       - asdf install uv latest

README.md

@@ -30,8 +30,9 @@ In concordance with the general SpatialData philosophy, all modalities of the ma
 
 For more information on the `spatialdata-plot` library, please refer to the [documentation](https://spatialdata.scverse.org/projects/plot/en/latest/index.html). In particular, the
 
+- [Gallery][link-gallery] — executable example notebooks demonstrating the plotting capabilities.
 - [API documentation][link-api].
-- [Example notebooks][link-notebooks] (section "Visiualizations")
+- [SpatialData example notebooks][link-notebooks] (section "Visualizations") for plotting in the context of broader analyses.
 
 ## Installation
 
@@ -65,6 +66,7 @@ Marconato, L., Palla, G., Yamauchi, K.A. et al. SpatialData: an open and univers
 [issue-tracker]: https://github.com/scverse/spatialdata-plot/issues
 [link-docs]: https://spatialdata-plot.readthedocs.io
 [link-api]: https://spatialdata.scverse.org/projects/plot/en/stable/api.html
+[link-gallery]: https://spatialdata.scverse.org/projects/plot/en/stable/gallery.html
 [link-design-doc]: https://spatialdata.scverse.org/en/stable/design_doc.html
 [link-notebooks]: https://spatialdata.scverse.org/en/stable/tutorials/notebooks/notebooks.html
 [//]: # "numfocus-fiscal-sponsor-attribution"

docs/_static/gallery/getting_started.png

@@ -56,6 +56,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
+    "sphinx_design",
     "sphinxcontrib.bibtex",
     "sphinxcontrib.katex",
     "sphinx_autodoc_typehints",

docs/conf.py

@@ -1,15 +1,41 @@
 # Gallery
 
 Curated, runnable examples demonstrating `spatialdata-plot` on real
-spatial-omics datasets (Visium, Xenium, MERFISH) and on the lightweight
-`blobs` dataset for first-time users.
+spatial-omics datasets and on the lightweight `blobs` dataset.
 
 Sources live in
 [`scverse/spatialdata-plot-notebooks`](https://github.com/scverse/spatialdata-plot-notebooks);
 every notebook is executable end-to-end and re-executed on a weekly schedule
 against the latest `spatialdata-plot` release.
 
+## Tutorials
+
+End-to-end workflows on real datasets.
+
+::::{grid} 1 2 2 2
+:gutter: 3
+
+:::{grid-item-card} Getting started
+:link: notebooks/tutorials/getting_started
+:link-type: doc
+:img-top: _static/gallery/getting_started.png
+
+The fluent `.pl` API, layering, and styling — on the in-memory `blobs`
+dataset. Ideal first read.
+:::
+
+::::
+
+## Examples
+
+```{note}
+No focused examples yet — contributions welcome! See
+[CONTRIBUTING](https://github.com/scverse/spatialdata-plot-notebooks/blob/main/CONTRIBUTING.md)
+in the notebooks repo for how to add one.
+```
+
 ```{toctree}
+:hidden:
 :maxdepth: 2
 
 notebooks/tutorials/index

docs/gallery.md

@@ -55,6 +55,7 @@ doc = [
   "sphinx-autodoc-typehints",
   "sphinx-book-theme>=1",
   "sphinx-copybutton",
+  "sphinx-design",
   "sphinx-tabs",
   "sphinxcontrib-bibtex>=1",
   "sphinxcontrib-katex",