enable interactive exploration of examples using jupyterlite-sphinx

.gitignore

@@ -89,6 +89,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
@@ -100,3 +103,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,46 @@
+#!/usr/bin/env python
+
+import pathlib
+import textwrap
+
+import vcs_versioning
+
+
+def find_pyproject(dir):
+    while dir != dir.root:
+        path = dir / "pyproject.toml"
+        if path.is_file():
+            return path
+
+        dir = dir.parent
+
+    raise RuntimeError("pyproject.toml can't be found")
+
+
+def main():
+    cwd = pathlib.Path(__file__).parent
+    pyproject_path = find_pyproject(cwd)
+    root = pyproject_path.parent
+
+    pyproject = vcs_versioning.PyProjectData.from_file(pyproject_path)
+    version = vcs_versioning.infer_version_string("xarray", pyproject)
+
+    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

@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS      = -T -W --keep-going -j auto
 SPHINXBUILD     = sphinx-build
-SPHINXATUOBUILD = sphinx-autobuild
+SPHINXAUTOBUILD = sphinx-autobuild
 PAPER           =
 BUILDDIR        = _build
 
@@ -52,6 +52,7 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf generated/*
 	rm -rf auto_gallery/
+	rm -rf jupyter_execute/
 
 .PHONY: html
 html:
@@ -68,8 +69,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,34 @@
     "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
+jupyterlite_bind_ipynb_suffix = False
+
+jupyterlite_content_dir = "_build/contents"
+
 # 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

@@ -295,6 +295,8 @@ Bug Fixes
 
 Documentation
 ~~~~~~~~~~~~~
+- Use ``jupyterlite-sphinx`` to provide interactive examples (:pull:`10299`).
+  By `Justus Magin <https://github.com/keewis>`_.
 
 - Add AI policy (:pull:`11257`).
   By `Nick Hodgskin <https://github.com/VeckoTheGecko>`_.

pixi.toml

@@ -1,6 +1,6 @@
 [workspace]
 preview = ["pixi-build"]
-channels = ["conda-forge", "nodefaults"]
+channels = ["conda-forge", "nodefaults", "https://prefix.dev/keewis-oss"]
 platforms = ["win-64", "linux-64", "osx-arm64"]
 requires-pixi = ">=0.63.2,!=0.68.0"
 
@@ -233,19 +233,29 @@ 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 = "*"
+# use the official version once https://github.com/jupyterlite/jupyterlite-sphinx/pull/346 has been resolved
+jupyterlite-sphinx = { version = "*", channel = "https://prefix.dev/keewis-oss" }
+jupyterlite-xeus = ">=4.4.1"
 make = "*"
 
 [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." }
 
 
@@ -370,6 +380,36 @@ rst-to-myst = { version = "*", extras = ["sphinx"] }
 [feature.tools.tasks]
 rst2myst = { cmd = "rst2myst", description = "Convert rst to myst markdown" }
 
+[feature.build-package.dependencies]
+vcs_versioning = "*"
+cytoolz = "*"
+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" },
+]
+
 [feature.numpydoc-lint.dependencies]
 numpydoc = "*"
 
@@ -504,6 +544,7 @@ doc = { features = [
   "accel",
   "viz",
   "extras",
+  "numba",
 ] }
 pre-commit = { features = ["pre-commit"], no-default-feature = true }
 release = { features = ["release"], no-default-feature = true }
@@ -521,3 +562,7 @@ default = { features = [
 policy = { features = ["policy"], no-default-feature = true }
 numpydoc-lint = { features = ["numpydoc-lint"] }
 tools = { features = ["tools"], no-default-feature = true }
+build-package = { features = [
+  "build-package",
+  "release",
+], no-default-feature = true }

pyproject.toml

@@ -101,12 +101,12 @@ dask = "xarray.namedarray.daskmanager:DaskManager"
 
 [build-system]
 build-backend = "setuptools.build_meta"
-requires = ["setuptools>=77.0.3", "setuptools-scm>=8"]
+requires = ["setuptools>=80", "setuptools-scm>=10", "vcs_versioning"]
 
 [tool.setuptools.packages.find]
 include = ["xarray*"]
 
-[tool.setuptools_scm]
+[tool.vcs-versioning]
 fallback_version = "9999"
 
 [tool.coverage.run]