Backport PR #4083 on branch 1.12.x (docs: use upstream APIs)

docs/extensions/array_support.py

@@ -7,6 +7,7 @@
 
 from docutils import nodes
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
 
 from scanpy._utils import _docs
 
@@ -179,7 +180,8 @@ def one[T](arg: Collection[T]) -> T | None:
     return item
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.add_directive("array-support", ArraySupport)
     app.add_config_value("array_support", {}, "env")
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/autosummary_skip_deprecated.py

@@ -4,6 +4,8 @@
 
 from typing import TYPE_CHECKING
 
+from sphinx.util.typing import ExtensionMetadata
+
 if TYPE_CHECKING:
     from typing import Literal
 
@@ -27,6 +29,7 @@ def skip_deprecated(  # noqa: PLR0917
     return None
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.connect("autodoc-skip-member", skip_deprecated)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/autosummary_skip_inherited.py

@@ -5,6 +5,8 @@
 from traceback import walk_stack
 from typing import TYPE_CHECKING
 
+from sphinx.util.typing import ExtensionMetadata
+
 if TYPE_CHECKING:
     from typing import Literal
 
@@ -54,6 +56,7 @@ def skip_inherited(  # noqa: PLR0917
     return True
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.connect("autodoc-skip-member", skip_inherited)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/canonical_tutorial.py

@@ -5,6 +5,7 @@
 from typing import TYPE_CHECKING
 
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
 
 if TYPE_CHECKING:
     from typing import ClassVar
@@ -22,6 +23,7 @@ def run(self) -> list[nodes.Node]:  # noqa: D102
         return []
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.add_directive("canonical-tutorial", CanonicalTutorial)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/debug_docstrings.py

@@ -8,10 +8,12 @@
 from typing import TYPE_CHECKING
 
 import sphinx.ext.napoleon
+from sphinx.util.typing import ExtensionMetadata
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
 
+
 _pd_orig = sphinx.ext.napoleon._process_docstring
 
 
@@ -21,7 +23,8 @@ def pd_new(app, what, name, obj, options, lines) -> None:  # noqa: PLR0917
     print(*lines, sep="\n")
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     if os.environ.get("DEBUG") is not None:
         sphinx.ext.napoleon._process_docstring = pd_new
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/function_images.py

@@ -5,6 +5,8 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from sphinx.util.typing import ExtensionMetadata
+
 if TYPE_CHECKING:
     from typing import Any
 
@@ -27,7 +29,8 @@ def insert_function_images(  # noqa: PLR0917
     ]
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.add_config_value("api_dir", Path(), "env")
     app.connect("autodoc-process-docstring", insert_function_images)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/git_ref.py

@@ -7,6 +7,8 @@
 from functools import lru_cache
 from typing import TYPE_CHECKING
 
+from sphinx.util.typing import ExtensionMetadata
+
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.config import Config
@@ -45,6 +47,7 @@ def set_ref(app: Sphinx, config: Config):
     app.config["html_theme_options"]["repository_branch"] = get() or "main"
 
 
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     app.connect("config-inited", set_ref)
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/myst_ignore_mime_types.py

@@ -0,0 +1,83 @@
+"""Extension to patch ignored mime types."""
+
+from __future__ import annotations
+
+import sys
+from importlib.abc import MetaPathFinder
+from importlib.metadata import Distribution, EntryPoint, EntryPoints
+from types import MappingProxyType
+from typing import TYPE_CHECKING, override
+
+from myst_nb.core.render import MimeRenderPlugin
+from sphinx.util.typing import ExtensionMetadata
+
+if TYPE_CHECKING:
+    import os
+    from collections.abc import Iterable, Sequence
+    from importlib.machinery import ModuleSpec
+    from importlib.metadata import DistributionFinder, SimplePath
+    from types import ModuleType
+
+    from docutils import nodes
+    from myst_nb.core.render import MimeData, NbElementRenderer
+    from sphinx.application import Sphinx
+
+
+ignore: set[str] = set()
+
+
+class _Ignore(MimeRenderPlugin):
+    @override
+    @staticmethod
+    def handle_mime(
+        renderer: NbElementRenderer, data: MimeData, inline: bool
+    ) -> None | list[nodes.Element]:
+        if data.mime_type in ignore:
+            return []  # returning a list instead of `None` means “we handled it”
+        return None
+
+
+class _IgnoreMimeDist(Distribution):
+    metadata = MappingProxyType(dict(Name=__name__, Version="0.0.0"))
+
+    @override
+    def read_text(self, filename: str) -> str | None:
+        return None
+
+    @override
+    def locate_file(self, path: str | os.PathLike[str]) -> SimplePath:
+        raise RuntimeError
+
+    @property
+    @override
+    def entry_points(self) -> EntryPoints:
+        ep = EntryPoint("ignore", f"{__name__}:_Ignore", "myst_nb.mime_renderers")
+        return EntryPoints([ep])
+
+
+class _IgnoreMimeFinder(MetaPathFinder):
+    def find_spec(
+        self,
+        fullname: str,
+        path: Sequence[str] | None,
+        target: ModuleType | None = None,
+    ) -> ModuleSpec | None:
+        return None
+
+    def find_distributions(
+        self, context: DistributionFinder.Context | None
+    ) -> Iterable[Distribution]:
+        """Find fake distribution."""
+        yield _IgnoreMimeDist()
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """App setup hook."""
+    global ignore  # noqa: PLW0603
+
+    app.add_config_value("myst_ignore_mime_types", [], "env")
+    ignore |= set(app.config.myst_ignore_mime_types)
+
+    sys.meta_path.append(_IgnoreMimeFinder())
+
+    return ExtensionMetadata(parallel_read_safe=True)

docs/extensions/param_police.py

@@ -6,10 +6,12 @@
 from typing import TYPE_CHECKING
 
 from sphinx.ext.napoleon import NumpyDocstring
+from sphinx.util.typing import ExtensionMetadata
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
 
+
 _format_docutils_params_orig = NumpyDocstring._format_docutils_params
 param_warnings = {}
 
@@ -46,7 +48,8 @@ def show_param_warnings(app, exception):
         raise RuntimeError(msg)
 
 
-def setup(app: Sphinx):
+def setup(app: Sphinx) -> ExtensionMetadata:
     """App setup hook."""
     NumpyDocstring._format_docutils_params = scanpy_log_param_types
     app.connect("build-finished", show_param_warnings)
+    return ExtensionMetadata(parallel_read_safe=True)

hatch.toml

@@ -4,11 +4,7 @@ dependency-groups = [ "dev" ]
 
 [envs.docs]
 dependency-groups = [ "doc" ]
-# MyST-NB 1.3.0 spams the doc build logs making debugging hard, so use https://github.com/executablebooks/MyST-NB/pull/704
-extra-dependencies = [
-    "pandas>=3",
-    "myst-nb @ git+https://github.com/executablebooks/MyST-NB.git@91273a686c66fd0383466c80eede61b208d7e426",
-]
+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"
 scripts.clean = "git clean -fdX -- {args:docs}"

pyproject.toml

@@ -118,7 +118,7 @@ test = [
 ]
 doc = [
     "ipython>=7.20",                        # for nbsphinx code highlighting
-    "myst-nb>=1",
+    "myst-nb>=1.4",
     "myst-parser>=2",
     "nbsphinx>=0.9",
     "sam-algorithm",