enable interactive exploration of examples using jupyterlite-sphinx

.gitignore

@@ -87,6 +87,9 @@ doc/videos-gallery.txt
 doc/*.zarr
 doc/*.nc
 doc/*.h5
+doc/_contents/
+.virtual_documents/
+.jupyterlite.doit.db
 
 # Until we support this properly, excluding from gitignore. (adding it to
 # gitignore to make it _easier_ to work with `uv`, not as an indication that I
@@ -98,3 +101,6 @@ xarray-docs/
 # pixi environments
 .pixi
 pixi.lock
+# recipe
+/ci/recipe/recipe.yaml
+/doc/environment.yml

.readthedocs.yaml

@@ -21,4 +21,5 @@ build:
       - pixi install --concurrent-solves 2 -e doc
     build:
       html:
+        - pixi run build
         - pixi run doc BUILDDIR=$READTHEDOCS_OUTPUT

ci/recipe/prepare_recipe.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+
+import pathlib
+import textwrap
+
+import git
+import packaging.version
+from tlz.itertoolz import last
+
+
+def dev_version(most_recent_release):
+    v = packaging.version.parse(str(most_recent_release))
+
+    next_version = (v.major, v.minor, v.micro + 1)
+    return str(v.__replace__(release=next_version, dev=0))
+
+
+def main():
+    repo = git.Repo(".")
+    root = pathlib.Path(repo.working_dir)
+
+    most_recent_release = last(list(repo.tags))
+    version = dev_version(most_recent_release)
+    recipe_root = root / "ci/recipe"
+
+    template_path = recipe_root / "recipe_template.yaml"
+    template = template_path.read_text()
+
+    context = textwrap.dedent(
+        f"""\
+        context:
+          name: xarray
+          version: {version}
+        """.rstrip()
+    )
+    recipe = "\n".join([context, "", template])  # noqa: FLY002
+    recipe_path = recipe_root / "recipe.yaml"
+    recipe_path.write_text(recipe)
+
+
+if __name__ == "__main__":
+    main()

ci/recipe/recipe_template.yaml

@@ -0,0 +1,41 @@
+package:
+  name: ${{ name }}
+  version: ${{ version }}
+
+source:
+  path: ../..
+
+build:
+  number: 0
+  noarch: python
+  script: SETUPTOOLS_SCM_PRETEND_VERSION=${{ version }} ${{ PYTHON }} -m pip install -vvv . --no-deps --no-build-isolation
+
+  files:
+    exclude:
+      - "**/__pycache__/**"
+      - "**/*.pyc"
+      - "**/test_*.py"
+  python:
+    skip_pyc_compilation:
+      - "**/*.py"
+
+requirements:
+  build:
+    - python
+  host:
+    - python
+    - pip
+    - setuptools
+    - setuptools-scm
+  run:
+    - python
+    - numpy
+    - pandas
+    - packaging
+
+about:
+  summary: N-D labeled arrays and datasets in Python
+  license: Apache-2.0
+  license_file: LICENSE
+  homepage: https://github.com/pydata/xarray
+  repository: https://github.com/pydata/xarray

doc/Makefile

@@ -2,9 +2,9 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS      =
+SPHINXOPTS      = -j auto
 SPHINXBUILD     = sphinx-build
-SPHINXATUOBUILD = sphinx-autobuild
+SPHINXAUTOBUILD = sphinx-autobuild
 PAPER           =
 BUILDDIR        = _build
 
@@ -68,8 +68,8 @@ rtdhtml:
 
 .PHONY: livehtml
 livehtml:
-	# @echo "$(SPHINXATUOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html"
-	$(SPHINXATUOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	# @echo "$(SPHINXAUTOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html"
+	$(SPHINXAUTOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
 .PHONY: dirhtml
 dirhtml:

doc/conf.py

@@ -64,6 +64,7 @@
     "sphinx_design",
     "sphinx_inline_tabs",
     "sphinx_remove_toctrees",
+    "jupyterlite_sphinx",
     "sphinx_llm.txt",
 ]
 
@@ -173,17 +174,31 @@
     "pd.Index": "~pandas.Index",
     "pd.NaT": "~pandas.NaT",
 }
-
 autodoc_type_aliases = napoleon_type_aliases  # Keep both in sync
 
+# jupyterlite try_examples config
+global_enable_try_examples = True
+try_examples_global_button_text = "Try it in your browser!"
+try_examples_global_warning_text = "Interactive examples are experimental and may not always work as expected."
+
+try_examples_preamble = """
+import numpy as np
+import pandas as pd
+import xarray as xr
+
+np.random.seed(0)
+""".strip()
+
+jupyterlite_silence = False
+
 # mermaid config
 mermaid_version = "11.6.0"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
 
-# The master toctree document.
-master_doc = "index"
+# The starting document.
+root_doc = "index"
 
 remove_from_toctrees = ["generated/*"]
 # The language for content autogenerated by Sphinx.

doc/create_environment.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+
+import pathlib
+
+
+def main():
+    root = pathlib.Path(__file__).parent
+
+    local_channel = root.parent / "local_channel"
+    package_paths = list(local_channel.joinpath("noarch").glob("xarray*.conda"))
+    if len(package_paths) != 1:
+        raise RuntimeError(f"zero or more than one package found: {package_paths}")
+
+    package_path = package_paths[0]
+
+    template_path = root / "environment_template.yml"
+    env_path = root / "environment.yml"
+
+    template = template_path.read_text()
+    environment = template.replace('"{{ local-package }}"', str(package_path))
+
+    env_path.write_text(environment)
+
+if __name__ == "__main__":
+    main()

doc/environment_template.yml

@@ -0,0 +1,29 @@
+name: xeus-python-kernel
+channels:
+  - https://prefix.dev/emscripten-forge-dev
+  - https://prefix.dev/conda-forge
+dependencies:
+  - xeus-python
+  - "{{ local-package }}"
+  - numpy
+  - pandas
+  - packaging
+  - boto3
+  - cartopy
+  - cftime
+  - h5netcdf
+  - h5py
+  - hdf5
+  - lxml # Optional dep of pydap
+  - matplotlib
+  - nc-time-axis
+  - netcdf4
+  - pint>=0.22
+  - pooch
+  - pydap
+  - rasterio
+  - scipy
+  - seaborn
+  - setuptools
+  - toolz
+  - zarr

doc/try_examples.json

@@ -0,0 +1,3 @@
+{
+  "global_min_height": "400px"
+}

doc/whats-new.rst

@@ -31,6 +31,8 @@ Bug Fixes
 
 Documentation
 ~~~~~~~~~~~~~
+- Use ``jupyterlite-sphinx`` to provide interactive examples (:pull:`10299`).
+  By `Justus Magin <https://github.com/keewis>`_.
 
 
 Internal Changes

pixi.toml

@@ -232,18 +232,27 @@ sphinx-copybutton = "*"
 sphinx-design = "*"
 sphinx-inline-tabs = "*"
 sphinx-llm = ">=0.2.1"
-sphinx = ">=6,<8"
+sphinx = ">=8,<9"
 sphinxcontrib-mermaid = "*"
 sphinxcontrib-srclinks = "*"
 sphinx-remove-toctrees = "*"
 sphinxext-opengraph = "*"
 sphinxext-rediraffe = "*"
 cfgrib = "*"
 myst-parser = "*"
+jupyterlite-sphinx = ">=0.22.1"
+jupyterlite-xeus = ">=4.4.1"
 
 [feature.doc.tasks]
-doc = { cmd = "make html", cwd = "doc", description = "Build the HTML documentation." }
-doc-clean = { cmd = "make clean && make html", cwd = "doc", description = "Clean build artifacts and rebuild the HTML documentation from scratch." }
+_prepare-environment = { cmd = "python create_environment.py", cwd = "doc" }
+doc = { cmd = "make html", cwd = "doc", description = "Build the HTML documentation.", depends-on = [
+  "_prepare-environment",
+] }
+doc-clean = { cmd = "make clean && make html", cwd = "doc", description = "Clean build artifacts and rebuild the HTML documentation from scratch.", depends-on = [
+  "build",
+  "_prepare-environment",
+] }
+host-static-doc = { cmd = "python -m http.server -b 127.0.0.1 -d _build/html 5455", cwd = "doc", description = "serve the static documentation" }
 linkcheck = { cmd = "make linkcheck", cwd = "doc", description = "Check URLs in documentation." }
 
 
@@ -341,6 +350,37 @@ rst-to-myst = { version = "*", extras = ["sphinx"] }
 [feature.tools.tasks]
 rst2myst = { cmd = "rst2myst", description = "Convert rst to myst markdown" }
 
+[feature.build-package.dependencies]
+gitpython = "*"
+cytoolz = "*"
+packaging = "*"
+rattler-build = "*"
+
+[feature.build-package.tasks.prepare-recipe]
+cmd = "python ci/recipe/prepare_recipe.py"
+cwd = "."
+
+[feature.build-package.tasks.build]
+cmd = [
+  "rattler-build",
+  "build",
+  "-c",
+  "conda-forge",
+  "--recipe",
+  "ci/recipe/recipe.yaml",
+  "--output-dir",
+  "local_channel",
+]
+cwd = "."
+depends-on = ["prepare-recipe"]
+
+[tasks]
+build-and-host-doc = [
+  { task = "build" },
+  { task = "doc" },
+  { task = "host-static-doc" },
+]
+
 [environments]
 # Testing
 # test-just-xarray = { features = ["test"] } # https://github.com/pydata/xarray/pull/10888/files#r2511336147
@@ -454,3 +494,7 @@ default = { features = [
 ] }
 policy = { features = ["policy"], no-default-feature = true }
 tools = { features = ["tools"], no-default-feature = true }
+build-package = { features = [
+  "build-package",
+  "release",
+], no-default-feature = true }