docs: switch to sphinx-exec-jupyter

docs/conf.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import os
 import shutil
 import sys
 from datetime import datetime
@@ -17,15 +16,11 @@
 from packaging.version import Version
 from sphinxcontrib.katex import NODEJS_BINARY
 
-# Don’t use tkinter agg when importing scanpy → … → matplotlib
-matplotlib.use("agg")
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
 
 HERE = Path(__file__).parent
 sys.path[:0] = [str(HERE.parent), str(HERE / "extensions")]
-os.environ["SPHINX_RUNNING"] = "1"  # for scanpy._singleton
-
-if TYPE_CHECKING:
-    from sphinx.application import Sphinx
 
 
 # -- General configuration ------------------------------------------------
@@ -73,9 +68,9 @@
     "sphinx.ext.coverage",
     "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
+    "sphinx_exec_jupyter",
     "sphinxcontrib.bibtex",
     "sphinxcontrib.katex",
-    "matplotlib.sphinxext.plot_directive",
     "sphinx_autodoc_typehints",  # needs to be after napoleon
     "git_ref",  # needs to be before scanpydoc.rtd_github_links
     "scanpydoc",  # needs to be before sphinx.ext.linkcode
@@ -105,6 +100,14 @@
 napoleon_custom_sections = [("Params", "Parameters")]
 todo_include_todos = False
 api_dir = HERE / "api"  # function_images
+exec_jupyter_code = """
+# setup notebook backend
+import matplotlib
+matplotlib.use("module://matplotlib_inline.backend_inline")
+# import all slow optional imports before running code
+import scanpy, umap, seaborn, sklearn.metrics, pynndescent, networkx
+del scanpy, umap, seaborn, sklearn, pynndescent, networkx, matplotlib
+"""
 myst_enable_extensions = [
     "amsmath",
     "colon_fence",
@@ -119,10 +122,12 @@
     "application/vnd.microsoft.datawrangler.viewer.v0+json",
 ]
 nb_output_stderr = "remove"
-nb_execution_mode = "off"
+nb_execution_mode = "cache"
+nb_execution_excludepatterns = [
+    f"{d}{'/*' * n}" for d in ["tutorials", "how-to"] for n in (1, 2, 3)
+]
 nb_merge_streams = True
 
-
 ogp_site_url = "https://scanpy.scverse.org/en/stable/"
 ogp_image = f"{ogp_site_url}_static/Scanpy_Logo_BrightFG.svg"
 

hatch.toml

@@ -3,7 +3,7 @@ installer = "uv"
 dependency-groups = [ "dev" ]
 
 [envs.docs]
-dependency-groups = [ "doc" ]
+dependency-groups = [ "docs" ]
 extra-dependencies = [ "pandas>=3" ]
 scripts.build = "sphinx-build -M html docs docs/_build -W {args}"
 scripts.open = "python3 -m webbrowser -t docs/_build/html/index.html"

pyproject.toml

@@ -115,7 +115,7 @@ test = [
     "zarr>=2.18.7",
     { include-group = "test-min" },
 ]
-doc = [
+docs = [
     "ipython>=8.27",                        # for nbsphinx code highlighting
     "myst-nb>=1.4",
     "myst-parser>=2",
@@ -131,6 +131,7 @@ doc = [
     "sphinx-book-theme>=1.1",
     "sphinx-copybutton",
     "sphinx-design",
+    "sphinx-exec-jupyter>=0.2.1",
     "sphinx-issues>=5.0.1",
     "sphinxcontrib-bibtex",
     "sphinxcontrib-katex",

src/scanpy/metrics/_metrics.py

@@ -53,7 +53,7 @@ def confusion_matrix(
     Examples
     --------
 
-    .. plot::
+    ..  exec-jupyter::
 
         import scanpy as sc; import seaborn as sns
         pbmc = sc.datasets.pbmc68k_reduced()

src/scanpy/plotting/_anndata.py

@@ -161,24 +161,21 @@ def scatter(  # noqa: PLR0913
     --------
     Plot two `.obs` annotations against each other and colour by a third.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()
         sc.pl.scatter(adata, x="n_counts", y="n_genes", color="bulk_labels")
 
     Plot expression of two genes against each other.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         sc.pl.scatter(adata, x="CD79A", y="CD3D", color="bulk_labels")
 
     Use a precomputed embedding via the `basis` argument.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         sc.pl.scatter(adata, basis="umap", color="bulk_labels")
 
@@ -618,8 +615,7 @@ def ranking(  # noqa: PLR0912, PLR0913
     PCA in :func:`~scanpy.datasets.pbmc68k_reduced` was computed on highly-variable
     genes only, so we subset to those genes before ranking.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()
@@ -628,8 +624,7 @@ def ranking(  # noqa: PLR0912, PLR0913
 
     Include the lowest-loading genes alongside the highest.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         sc.pl.ranking(adata_hv, attr="varm", keys="PCs", indices=[0, 1, 2], include_lowest=True)
 
@@ -801,41 +796,36 @@ def violin(  # noqa: PLR0912, PLR0913, PLR0915
     Examples
     --------
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()
         sc.pl.violin(adata, keys='S_score')
 
     Plot by category. Rotate x-axis labels so that they do not overlap.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         sc.pl.violin(adata, keys='S_score', groupby='bulk_labels', rotation=90)
 
     Set order of categories to be plotted or select specific categories to be plotted.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         groupby_order = ['CD34+', 'CD19+ B']
         sc.pl.violin(adata, keys='S_score', groupby='bulk_labels', rotation=90,
             order=groupby_order)
 
     Plot multiple keys.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         sc.pl.violin(adata, keys=['S_score', 'G2M_score'], groupby='bulk_labels',
             rotation=90)
 
     For large datasets consider omitting the overlaid scatter plot.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         sc.pl.violin(adata, keys='S_score', stripplot=False)
 
@@ -1022,15 +1012,13 @@ def clustermap(
     Examples
     --------
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.krumsiek11()
         sc.pl.clustermap(adata)
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         sc.pl.clustermap(adata, obs_keys='cell_type')
 
@@ -1126,8 +1114,7 @@ def heatmap(  # noqa: PLR0912, PLR0913, PLR0915
 
     Examples
     --------
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()
@@ -1495,8 +1482,7 @@ def tracksplot(  # noqa: PLR0912, PLR0913, PLR0915
     --------
     Using var_names as list:
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()
@@ -1505,8 +1491,7 @@ def tracksplot(  # noqa: PLR0912, PLR0913, PLR0915
 
     Using var_names as dict:
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         markers = {{'T-cell': 'CD3D', 'B-cell': 'CD79A', 'myeloid': 'CST3'}}
         sc.pl.tracksplot(adata, markers, groupby='bulk_labels', dendrogram=True)
@@ -1754,8 +1739,7 @@ def dendrogram(
 
     Examples
     --------
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()
@@ -1829,8 +1813,7 @@ def correlation_matrix(  # noqa: PLR0912, PLR0913, PLR0915
     --------
     Plot correlation matrix between cell type groups.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()

src/scanpy/plotting/_dotplot.py

@@ -1063,8 +1063,7 @@ def dotplot(  # noqa: PLR0913
     Create a dot plot using the given markers and the PBMC example dataset grouped by
     the category `'bulk_labels'`.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()
@@ -1073,8 +1072,7 @@ def dotplot(  # noqa: PLR0913
 
     Grouping `var_names` as well and specifying group colors for `groupby`:
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         from matplotlib import cm
         markers = {{'T-cell': 'CD3D', 'B-cell': 'CD79A', 'myeloid': 'CST3'}}
@@ -1083,8 +1081,7 @@ def dotplot(  # noqa: PLR0913
 
     Get `DotPlot` object for fine tuning
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         dp = sc.pl.dotplot(adata, markers, 'bulk_labels', return_fig=True)
         dp.add_totals().style(dot_edge_color='black', dot_edge_lw=0.5).show()

src/scanpy/plotting/_matrixplot.py

@@ -58,17 +58,18 @@ class MatrixPlot(BasePlot):
 
     See Also
     --------
-    :func:`~scanpy.pl.matrixplot`: Simpler way to call MatrixPlot but with less options.
-    :func:`~scanpy.pl.rank_genes_groups_matrixplot`: to plot marker genes identified
+    :func:`~scanpy.pl.matrixplot`
+        Simpler way to call MatrixPlot but with less options.
+    :func:`~scanpy.pl.rank_genes_groups_matrixplot`
+        to plot marker genes identified
         using the :func:`~scanpy.tl.rank_genes_groups` function.
 
     Examples
     --------
     Simple visualization of the average expression of a few genes grouped by
     the category 'bulk_labels'.
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()
@@ -78,8 +79,7 @@ class MatrixPlot(BasePlot):
     Same visualization but passing var_names as dict, which adds a grouping of
     the genes on top of the image:
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         markers = {{'T-cell': 'CD3D', 'B-cell': 'CD79A', 'myeloid': 'CST3'}}
         sc.pl.MatrixPlot(adata, markers, groupby='bulk_labels').show()
@@ -201,8 +201,7 @@ def style(
         Examples
         --------
 
-        .. plot::
-            :context: close-figs
+        ..  exec-jupyter::
 
             import scanpy as sc
 
@@ -212,8 +211,7 @@ def style(
         Change color map and turn off edges:
 
 
-        .. plot::
-            :context: close-figs
+        ..  exec-jupyter::
 
             (
                 sc.pl.MatrixPlot(adata, markers, groupby='bulk_labels')
@@ -358,8 +356,7 @@ def matrixplot(  # noqa: PLR0913
     Examples
     --------
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         import scanpy as sc
         adata = sc.datasets.pbmc68k_reduced()
@@ -368,24 +365,21 @@ def matrixplot(  # noqa: PLR0913
 
     Using var_names as dict:
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         markers = {{'T-cell': 'CD3D', 'B-cell': 'CD79A', 'myeloid': 'CST3'}}
         sc.pl.matrixplot(adata, markers, groupby='bulk_labels', dendrogram=True)
 
     Get Matrix object for fine tuning:
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         mp = sc.pl.matrixplot(adata, markers, 'bulk_labels', return_fig=True)
         mp.add_totals().style(edge_color='black').show()
 
     The axes used can be obtained using the get_axes() method
 
-    .. plot::
-        :context: close-figs
+    ..  exec-jupyter::
 
         axes_dict = mp.get_axes()