Add docs gallery via spatialdata-plot-notebooks submodule#656
Merged
Conversation
Mounts scverse/spatialdata-plot-notebooks at docs/notebooks/ and renders it into the docs as a Gallery section, following the scverse convention used by anndata, spatialdata, scvi-tools, and squidpy. Notebooks are pre-executed by humans and committed with outputs in the notebooks repo; this docs build performs no execution. RTD pulls the submodule on each build (submodules.include = all). A new `docs` job in build.yaml runs the docs build on every PR with submodules checked out, gating sphinx warnings (-W) before merge. conf.py exclude_patterns: drop stale `tutorials/notebooks/...` entries (directory was never created), exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings. Closes the gallery scope from #463; supersedes the sphinx-gallery approach proposed in #590.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #656 +/- ##
==========================================
+ Coverage 77.04% 77.07% +0.03%
==========================================
Files 11 11
Lines 3280 3280
Branches 774 774
==========================================
+ Hits 2527 2528 +1
Misses 454 454
+ Partials 299 298 -1 🚀 New features to boost your workflow:
|
Replaces the now-stale "Tutorials with myst-nb" section with concrete instructions for the submodule-based gallery: how to clone with submodules, how to bump the pin, and where to send notebook PRs (the notebooks repo). Adds a heads-up admonition to the "Building the docs locally" section so contributors who cloned without --recurse-submodules know to run `git submodule update --init --recursive` before sphinx-build.
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.
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
2 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.
Inspired by #590 by user asarigun
Summary
Mounts
scverse/spatialdata-plot-notebooksatdocs/notebooks/as a git submodule and renders it into the docs as a new Gallery section. Follows the scverse convention used byanndata,spatialdata,scvi-tools, andsquidpy(pre-rendered notebooks viamyst-nb,nb_execution_mode = "off").This supersedes the sphinx-gallery approach proposed in #590 — see "Why this approach" below — and addresses the missing-gallery gap identified in #463.
Changes
.gitmodulesdocs/notebooks→scverse/spatialdata-plot-notebooks(branchmain).docs/gallery.mdtutorials/indexandexamples/index.docs/index.mdgallery.mdto the top-level toctree.docs/conf.pyexclude_patterns: drop staletutorials/notebooks/...entries (dir was never created); exclude submodule meta-files (README, CONTRIBUTING, LICENSE, .github, pyproject.toml) so they don't trigger toctree warnings..readthedocs.yamlsubmodules: include: allso RTD pulls the notebooks repo on each build..github/workflows/build.yamldocsjob that builds docs on every PR with submodules checked out — first time docs builds are PR-gated.No new dependencies. The notebooks repo's
pyproject.tomlcarriessquidpyand other heavy tutorial deps; this repo'sdocgroup is unchanged.Why this approach
*-notebooks-repo pattern withnb_execution_mode = "off". Sphinx-gallery is unused across scverse.getting_started.ipynbalready shipped in the notebooks repo runssd.datasets.blobs()(in-memory, no download). Heavier tutorials (Visium, Xenium, MERFISH) will fetch viasquidpy.datasets.*when contributors execute them locally — the docs build only renders pre-committed outputs.execute.yamlworkflow re-executes every notebook weekly (and on PR) against the latestspatialdata-plotrelease, catching silent regressions vianbdimediff without blocking lib PRs.