docs: Sphinx 9 support and MyST-parser fixes (#3948)

flying-sheep · web-flow · commit 651444ee7998 · 2026-01-19T20:05:53.000+01:00
diff --git a/docs/api/classes.md b/docs/api/classes.md
@@ -1,4 +1,4 @@
-## Classes
+# Classes
 
 
 ```{eval-rst}
diff --git a/docs/api/datasets.md b/docs/api/datasets.md
@@ -1,4 +1,4 @@
-## Datasets
+# Datasets
 
 ```{eval-rst}
 .. module:: scanpy.datasets
diff --git a/docs/api/deprecated.md b/docs/api/deprecated.md
@@ -1,4 +1,4 @@
-## Deprecated functions
+# Deprecated functions
 
 ```{eval-rst}
 .. currentmodule:: scanpy
diff --git a/docs/api/experimental.md b/docs/api/experimental.md
@@ -1,6 +1,4 @@
-
-
-## Experimental
+# Experimental
 
 ```{eval-rst}
 .. module:: scanpy.experimental
diff --git a/docs/api/get.md b/docs/api/get.md
@@ -1,4 +1,4 @@
-## Get object from `AnnData`: `get`
+# Get object from `AnnData`: `get`
 
 ```{eval-rst}
 .. module:: scanpy.get
diff --git a/docs/api/io.md b/docs/api/io.md
@@ -1,7 +1,7 @@
 (reading)=
 (reading-and-writing)=
 
-## Reading and Writing
+# Reading and Writing
 
 ```{eval-rst}
 .. currentmodule:: scanpy
diff --git a/docs/api/metrics.md b/docs/api/metrics.md
@@ -1,4 +1,4 @@
-## Metrics
+# Metrics
 
 ```{eval-rst}
 .. module:: scanpy.metrics
diff --git a/docs/api/plotting.md b/docs/api/plotting.md
@@ -1,4 +1,4 @@
-## Plotting: `pl`
+# Plotting: `pl`
 
 ```{eval-rst}
 .. module:: scanpy.pl
@@ -19,7 +19,7 @@ See the {ref}`settings` section for all important plotting configurations.
 
 (pl-generic)=
 
-### Generic
+## Generic
 
 ```{eval-rst}
 .. autosummary::
@@ -39,7 +39,7 @@ See the {ref}`settings` section for all important plotting configurations.
 
 ```
 
-### Classes
+## Classes
 
 These classes allow fine tuning of visual parameters.
 
@@ -54,7 +54,7 @@ These classes allow fine tuning of visual parameters.
 
 ```
 
-### Preprocessing
+## Preprocessing
 
 Methods for visualizing quality control and results of preprocessing functions.
 
@@ -69,13 +69,13 @@ Methods for visualizing quality control and results of preprocessing functions.
 
 ```
 
-### Tools
+## Tools
 
 Methods that extract and visualize tool-specific annotation in an
 {class}`~anndata.AnnData` object.  For any method in module `tl`, there is
 a method with the same name in `pl`.
 
-#### PCA
+### PCA
 
 ```{eval-rst}
 .. autosummary::
@@ -90,7 +90,7 @@ a method with the same name in `pl`.
 
 (pl-embeddings)=
 
-#### Embeddings
+### Embeddings
 
 ```{eval-rst}
 .. autosummary::
@@ -115,7 +115,7 @@ Compute densities on embeddings.
    pl.embedding_density
 ```
 
-#### Branching trajectories and pseudotime, clustering
+### Branching trajectories and pseudotime, clustering
 
 Visualize clusters using one of the embedding methods passing e.g. `color='leiden'`.
 
@@ -141,7 +141,7 @@ Visualize hierarchical clustering results as a heatmap.
    pl.correlation_matrix
 ```
 
-#### Marker genes
+### Marker genes
 
 ```{eval-rst}
 .. autosummary::
@@ -157,7 +157,7 @@ Visualize hierarchical clustering results as a heatmap.
    pl.rank_genes_groups_tracksplot
 ```
 
-#### Simulations
+### Simulations
 
 ```{eval-rst}
 .. autosummary::
diff --git a/docs/api/preprocessing.md b/docs/api/preprocessing.md
@@ -1,4 +1,4 @@
-## Preprocessing: `pp`
+# Preprocessing: `pp`
 
 ```{eval-rst}
 .. module:: scanpy.pp
@@ -12,7 +12,7 @@ Filtering of highly-variable genes, batch-effect correction, per-cell normalizat
 
 Any transformation of the data matrix that is not a *tool*. Other than *tools*, preprocessing steps usually don't return an easily interpretable annotation, but perform a basic transformation on the data matrix.
 
-### Basic Preprocessing
+## Basic Preprocessing
 
 For visual quality control, see {func}`~scanpy.pl.highest_expr_genes` and
 {func}`~scanpy.pl.filter_genes_dispersion` in {mod}`scanpy.pl`.
@@ -35,7 +35,7 @@ For visual quality control, see {func}`~scanpy.pl.highest_expr_genes` and
    pp.downsample_counts
 ```
 
-### Recipes
+## Recipes
 
 ```{eval-rst}
 .. autosummary::
@@ -47,7 +47,7 @@ For visual quality control, see {func}`~scanpy.pl.highest_expr_genes` and
    pp.recipe_seurat
 ```
 
-### Batch effect correction
+## Batch effect correction
 
 Also see {ref}`data-integration`. Note that a simple batch correction method is available via {func}`pp.regress_out`. Checkout {mod}`scanpy.external` for more.
 
@@ -59,7 +59,7 @@ Also see {ref}`data-integration`. Note that a simple batch correction method is
    pp.combat
 ```
 
-### Doublet detection
+## Doublet detection
 
 ```{eval-rst}
 .. autosummary::
@@ -70,7 +70,7 @@ Also see {ref}`data-integration`. Note that a simple batch correction method is
    pp.scrublet_simulate_doublets
 ```
 
-### Neighbors
+## Neighbors
 
 ```{eval-rst}
 .. autosummary::
diff --git a/docs/api/queries.md b/docs/api/queries.md
@@ -1,4 +1,4 @@
-## Queries
+# Queries
 
 ```{eval-rst}
 .. module:: scanpy.queries
diff --git a/docs/api/settings.md b/docs/api/settings.md
@@ -1,6 +1,6 @@
 (settings)=
 
-## Settings
+# Settings
 
 
 ```{eval-rst}
diff --git a/docs/api/tools.md b/docs/api/tools.md
@@ -1,4 +1,4 @@
-## Tools: `tl`
+# Tools: `tl`
 
 ```{eval-rst}
 .. module:: scanpy.tl
@@ -10,7 +10,7 @@
 
 Any transformation of the data matrix that is not *preprocessing*. In contrast to a *preprocessing* function, a *tool* usually adds an easily interpretable annotation to the data matrix, which can then be visualized with a corresponding plotting function.
 
-### Embeddings
+## Embeddings
 
 ```{eval-rst}
 .. autosummary::
@@ -34,7 +34,7 @@ Compute densities on embeddings.
    tl.embedding_density
 ```
 
-### Clustering and trajectory inference
+## Clustering and trajectory inference
 
 ```{eval-rst}
 .. autosummary::
@@ -49,7 +49,7 @@ Compute densities on embeddings.
 
 (data-integration)=
 
-### Data integration
+## Data integration
 
 ```{eval-rst}
 .. autosummary::
@@ -59,7 +59,7 @@ Compute densities on embeddings.
    tl.ingest
 ```
 
-### Marker genes
+## Marker genes
 
 ```{eval-rst}
 .. autosummary::
@@ -71,7 +71,7 @@ Compute densities on embeddings.
    tl.marker_gene_overlap
 ```
 
-### Gene scores, Cell cycle
+## Gene scores, Cell cycle
 
 ```{eval-rst}
 .. autosummary::
@@ -82,7 +82,7 @@ Compute densities on embeddings.
    tl.score_genes_cell_cycle
 ```
 
-### Simulations
+## Simulations
 
 ```{eval-rst}
 .. autosummary::
diff --git a/docs/conf.py b/docs/conf.py
@@ -31,10 +31,6 @@
 
 nitpicky = True  # Warn about broken links. This is here for a reason: Do not change.
 needs_sphinx = "4.0"  # Nicer param docs
-suppress_warnings = [
-    "myst.header",  # https://github.com/executablebooks/MyST-Parser/issues/262
-    "mystnb.unknown_mime_type",  # application/vnd.microsoft.datawrangler.viewer.v0+json
-]
 
 # General information
 project = "Scanpy"
@@ -85,13 +81,13 @@
     "sphinx.ext.linkcode",
     "sphinx_design",
     "sphinx_issues",
-    "sphinx_tabs.tabs",
     "sphinxext.opengraph",
     *[p.stem for p in (HERE / "extensions").glob("*.py") if p.stem not in {"git_ref"}],
 ]
 
 # Generate the API documentation when building
 autosummary_generate = True
+autodoc_typehints = "none"
 autodoc_member_order = "bysource"
 autodoc_default_options = {
     # Don’t show members in addition to the autosummary table added by `_templates/class.rst`
@@ -117,6 +113,9 @@
 ]
 myst_url_schemes = ("http", "https", "mailto", "ftp")
 myst_heading_anchors = 3
+myst_ignore_mime_types = [  # from custom extension patch_myst_nb
+    "application/vnd.microsoft.datawrangler.viewer.v0+json",
+]
 nb_output_stderr = "remove"
 nb_execution_mode = "off"
 nb_merge_streams = True
diff --git a/docs/extensions/patch_myst_nb.py b/docs/extensions/patch_myst_nb.py
@@ -7,17 +7,21 @@
 from copy import copy
 from typing import TYPE_CHECKING
 
-from myst_nb.core.render import MditRenderMixin
+from myst_nb.core.render import MditRenderMixin, NbElementRenderer
 
 if TYPE_CHECKING:
+    from docutils import nodes
+    from myst_nb.core.render import MimeData, SelfType
     from sphinx.application import Sphinx
 
 
 get_orig = MditRenderMixin.get_cell_level_config
+ru_orig = NbElementRenderer.render_unhandled
+ru_i_orig = NbElementRenderer.render_unhandled_inline
 
 
 def get_cell_level_config(
-    self: MditRenderMixin,
+    self: SelfType,
     field: str,
     cell_metadata: dict[str, object],
     line: int | None = None,
@@ -27,6 +31,23 @@ def get_cell_level_config(
     return copy(rv)
 
 
-def setup(app: Sphinx):
+def setup(app: Sphinx) -> None:
     """App setup hook."""
+    app.add_config_value("myst_ignore_mime_types", [], "env")
+    ignore = set(app.config.myst_ignore_mime_types)
+
+    def render_unhandled(
+        self: NbElementRenderer, data: MimeData
+    ) -> list[nodes.Element]:
+        if data.mime_type in ignore:
+            return []
+        return ru_orig(self, data)
+
+    def render_unh_i(self: NbElementRenderer, data: MimeData) -> list[nodes.Element]:
+        if data.mime_type in ignore:
+            return []
+        return ru_i_orig(self, data)
+
     MditRenderMixin.get_cell_level_config = get_cell_level_config
+    NbElementRenderer.render_unhandled = render_unhandled
+    NbElementRenderer.render_unhandled_inline = render_unh_i
diff --git a/docs/external/exporting.md b/docs/external/exporting.md
@@ -1,4 +1,4 @@
-## Exporting
+# Exporting
 
 ```{eval-rst}
 .. module:: scanpy.external.exporting
diff --git a/docs/external/plotting.md b/docs/external/plotting.md
@@ -1,4 +1,4 @@
-## Plotting: PL
+# Plotting: PL
 
 
 ```{eval-rst}
diff --git a/docs/external/preprocessing.md b/docs/external/preprocessing.md
@@ -1,4 +1,4 @@
-## Preprocessing: PP
+# Preprocessing: PP
 
 ```{eval-rst}
 .. module:: scanpy.external.pp
@@ -7,7 +7,7 @@
 
 (external-data-integration)=
 
-### Data integration
+## Data integration
 
 ```{eval-rst}
 .. autosummary::
@@ -20,7 +20,7 @@
 
 ```
 
-### Sample demultiplexing
+## Sample demultiplexing
 
 ```{eval-rst}
 .. autosummary::
@@ -29,7 +29,7 @@
    pp.hashsolo
 ```
 
-### Imputation
+## Imputation
 
 Note that the fundamental limitations of imputation are still under [debate](https://github.com/scverse/scanpy/issues/189).
 
diff --git a/docs/external/tools.md b/docs/external/tools.md
diff --git a/docs/installation.md b/docs/installation.md
diff --git a/docs/news.md b/docs/news.md
diff --git a/docs/tutorials/experimental/index.md b/docs/tutorials/experimental/index.md
diff --git a/docs/tutorials/trajectories/index.md b/docs/tutorials/trajectories/index.md
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Classes`
	`1`	`+# Classes`
`2`	`2`
`3`	`3`
`4`	`4`	```{eval-rst}
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Datasets`
	`1`	`+# Datasets`
`2`	`2`
`3`	`3`	```{eval-rst}
`4`	`4`	`.. module:: scanpy.datasets`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Deprecated functions`
	`1`	`+# Deprecated functions`
`2`	`2`
`3`	`3`	```{eval-rst}
`4`	`4`	`.. currentmodule:: scanpy`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-## Get object from `AnnData`: `get`
	`1`	+# Get object from `AnnData`: `get`
`2`	`2`
`3`	`3`	```{eval-rst}
`4`	`4`	`.. module:: scanpy.get`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Metrics`
	`1`	`+# Metrics`
`2`	`2`
`3`	`3`	```{eval-rst}
`4`	`4`	`.. module:: scanpy.metrics`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-## Queries`
	`1`	`+# Queries`
`2`	`2`
`3`	`3`	```{eval-rst}
`4`	`4`	`.. module:: scanpy.queries`