ENH: Add JupyterLite sphinx integration and CI/CD infrastructure

Integrates jupyterlite-sphinx into the MNE-Python doc build so every
sphinx-gallery example gets a 'Try in Browser' button backed by a
Pyodide/WebAssembly kernel.

- doc/conf.py: configure jupyterlite_sphinx; build a local MNE dev
  wheel with relaxed Pyodide constraints; copy required MNE sample-data
  subset into JupyterLite's virtual filesystem; inject a setup cell that
  installs MNE via micropip (keep_going=True bypasses version conflicts),
  mocks missing stdlib modules (lzma, multiprocessing), patches pooch to
  block large OSF downloads, and sets MNE_DATA paths
- .circleci/config.yml: ensure MNE sample data is on disk before the
  doc build so conf.py can copy it into jupyterlite_contents/
- .github/workflows/jupyterlite.yml: standalone GH Actions workflow on
  the jupyterlite-gh-actions branch that builds and uploads the site
- pyproject.toml: add jupyterlite-pyodide-kernel and jupyterlite-sphinx
  to the [doc] extras
- .gitignore: exclude jupyterlite_contents build artifacts

Author: natinew77-creator

.circleci/config.yml

@@ -21,14 +21,17 @@ _check_skip: &check_skip
       circleci-agent step halt;
     fi
 
+_machine_image: &machine_image
+  image: ubuntu-2604:2026.05.1
+
 jobs:
   build_docs:
     parameters:
       scheduled:
         type: string
         default: "false"
     machine:
-      image: ubuntu-2404:current
+      <<: *machine_image
     # large 4 vCPUs 15GB mem
     # https://discuss.circleci.com/t/changes-to-remote-docker-reporting-pricing/47759
     resource_class: large
@@ -62,6 +65,9 @@ jobs:
             if [[ $(cat merge.txt) != "" ]]; then
               echo "Merging $(cat merge.txt)";
               git pull --ff-only upstream "refs/pull/$(cat merge.txt)/merge";
+            elif [[ "$CIRCLE_PROJECT_USERNAME" != "mne-tools" ]]; then
+              echo "On CIRCLE_PROJECT_USERNAME=\"$CIRCLE_PROJECT_USERNAME\" repo rather than mne-tools, merging upstream/main."
+              git merge upstream/main --no-edit || exit 1
             else
               if [[ "$CIRCLE_BRANCH" == "main" ]]; then
                 KIND=dev
@@ -107,7 +113,7 @@ jobs:
       # Load pip cache
       - restore_cache:
           keys:
-            - pip-cache-0
+            - pip-cache-1
       - restore_cache:
           keys:
             - user-install-bin-cache-310
@@ -119,7 +125,7 @@ jobs:
             ./tools/circleci_dependencies.sh
 
       - save_cache:
-          key: pip-cache-0
+          key: pip-cache-1
           paths:
             - ~/.cache/pip
       - save_cache:
@@ -219,7 +225,7 @@ jobs:
           keys:
             - data-cache-ds004388
       - run:
-          name: Get data
+          name: Get data and triage examples to run
           # This limit could be increased, but this is helpful for finding slow ones
           # (even ~2GB datasets should be downloadable in this time from good
           # providers)
@@ -243,6 +249,16 @@ jobs:
               cp junit-results.xml doc/_build/test-results/test-doc/junit.xml;
               cp coverage.xml doc/_build/test-results/test-doc/coverage.xml;
             fi;
+      # Ensure the MNE sample dataset is on disk so conf.py can copy the
+      # required subset into jupyterlite_contents/ for the JupyterLite build.
+      # circleci_download.sh only fetches sample data when the changed files
+      # reference it, so a cache miss on a PR that touches only doc/conf.py
+      # would leave ~/mne_data/MNE-sample-data absent and the notebooks would
+      # fail at runtime with FileNotFoundError on /drive/mne_data.
+      - run:
+          name: Ensure MNE sample data for JupyterLite
+          command: |
+            python -c "import mne; mne.datasets.sample.data_path(update_path=True)"
       # Build docs
       - run:
           name: make html
@@ -416,7 +432,7 @@ jobs:
         type: string
         default: "false"
     machine:
-      image: ubuntu-2404:current
+      <<: *machine_image
     resource_class: large
     steps:
       - restore_cache:
@@ -436,7 +452,7 @@ jobs:
           command: ./tools/circleci_bash_env.sh
       - restore_cache:
           keys:
-            - pip-cache-0
+            - pip-cache-1
       - run:
           name: Get Python running
           command: |
@@ -457,7 +473,7 @@ jobs:
 
   deploy:
     machine:
-      image: ubuntu-2404:current
+      <<: *machine_image
     steps:
       - attach_workspace:
           at: /tmp/build

.github/workflows/jupyterlite.yml

@@ -0,0 +1,46 @@
+name: Build JupyterLite
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - jupyterlite-gh-actions
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build JupyterLite Site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install JupyterLite & Build Tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install jupyterlite-core jupyterlite-pyodide-kernel build jupyter-server
+
+      - name: Build MNE-Python Wheel
+        run: |
+          python -m build --wheel
+          mkdir -p lite-wheels
+          cp dist/*.whl lite-wheels/
+
+      - name: Build JupyterLite Site
+        # We pass the local wheel to JupyterLite so the browser environment uses the exact code from this branch!
+        run: |
+          jupyter lite build --contents examples/ --output-dir dist_lite/ --piplite-wheel lite-wheels/*.whl
+
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: jupyterlite-build
+          path: dist_lite/

.gitignore

@@ -74,6 +74,7 @@ tags
 /doc/fil-result
 /doc/optipng.exe
 /doc/sphinxext/.joblib
+/doc/code_credit.inc
 sg_execution_times.rst
 sg_api_usage.rst
 sg_api_unused.dot
@@ -102,3 +103,5 @@ venv/
 .hypothesis/
 .ruff_cache/
 .ipynb_checkpoints/
+jupyterlite_contents/auto_tutorials
+jupyterlite_contents/mne_data

doc/changes/dev/13925.newfeature.rst

@@ -0,0 +1 @@
+Added a JupyterLite GitHub Actions workflow to automatically build a Wasm-compatible interactive documentation site by Natneal Belete.