DOC add interactive example via Jupyterlite (#173)

MatthewSZhang · web-flow · commit 05533fd6abee · 2025-09-23T19:05:53.000+08:00
* DOC use xeus kernel

* use conda-forge

* add plantuml

* remove rtd_pre_install

* use conda openjdk

* add note in forecasting example
diff --git a/.github/workflows/asv.yml b/.github/workflows/asv.yml
@@ -39,7 +39,7 @@ jobs:
       - name: Run benchmarks
         shell: bash
         run: |
-          MACHINE=${{ matrix.os }} pixi run asv-build
+          pixi run asv-build ${{ matrix.os }}
 
       - name: Upload benchmark results
         uses: actions/upload-artifact@v4
diff --git a/.github/workflows/emscripten.yml b/.github/workflows/emscripten.yml
@@ -9,7 +9,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - name: Build WASM wheel
-        uses: pypa/cibuildwheel@v3.1.4
+        uses: pypa/cibuildwheel@v3.2.0
         env:
           CIBW_PLATFORM: pyodide
       - name: Upload package
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -32,18 +32,17 @@ jobs:
         run: |
           pixi run -e dev test
       - name: Test with doctest
-        shell: bash
+        if: matrix.os == 'ubuntu-latest'
         run: |
           pixi run -e dev doc
-          CMD=doctest pixi run -e dev doc
+          pixi run -e dev doc sphinx-build doctest
       - name: Test nogil
         run: |
           pixi run -e nogil nogil-eta
       - name: Test coverage
         if: matrix.os == 'ubuntu-latest'
-        shell: bash
         run: |
-          FMT=xml pixi run -e dev test-coverage
+          pixi run -e dev test-coverage xml
       - name: Upload coverage reports to Codecov
         if: matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@v5
diff --git a/.github/workflows/wheel.yml b/.github/workflows/wheel.yml
@@ -33,7 +33,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - name: Build wheels
-        uses: pypa/cibuildwheel@v3.1.4
+        uses: pypa/cibuildwheel@v3.2.0
         env:
           CIBW_SKIP: "*_i686 *_ppc64le *_s390x *_universal2 *-musllinux_* cp314t*"
           CIBW_PROJECT_REQUIRES_PYTHON: ">=3.10"
diff --git a/.gitignore b/.gitignore
@@ -30,4 +30,8 @@ wheels/
 doc/_build/
 doc/generated/
 doc/auto_examples/
-doc/sg_execution_times.rst
+doc/sg_execution_times.rst
+doc/.jupyterlite.doit.db
+doc/jupyterlite_contents/
+doc/_contents/
+emsdk/
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,21 +1,12 @@
 version: 2
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.13"
-  apt_packages:
-    - default-jre # for plantuml
-    - graphviz # for plantuml
-  jobs:
-    pre_install:
-      - bash scripts/rtd_pre_install.sh
+    python: "mambaforge-latest"
+
+conda:
+  environment: rtd-environment.yml
 
 sphinx:
    configuration: doc/conf.py
-   fail_on_warning: true
-
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements: [docs]
+   fail_on_warning: true
diff --git a/doc/conf.py b/doc/conf.py
@@ -43,6 +43,8 @@
     "sphinx_design",
     # For PlantUML diagrams
     "sphinxcontrib.plantuml",
+    # For interactive examples via JupyterLite
+    'jupyterlite_sphinx',
 ]
 
 # List of patterns, relative to source directory, that match files and
@@ -67,7 +69,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 # Third-party theme: pip install furo
 html_theme = "furo"
-html_static_path = ["images"]
+html_static_path = ["images", "css"]
 
 
 # intersphinx configuration
@@ -79,3 +81,14 @@
     "examples_dirs": ["../examples"],
     "gallery_dirs": ["auto_examples"],
 }
+
+# -----------------------------------------------------------------------------
+# Interactive documentation examples via JupyterLite
+# -----------------------------------------------------------------------------
+
+global_enable_try_examples = True
+try_examples_global_button_text = "Try it in your browser!"
+try_examples_global_warning_text = (
+    "If you encounter any issues, please report them on the"
+    " [fastcan issue tracker](https://github.com/scikit-learn-contrib/fastcan/issues)."
+)
diff --git a/doc/css/fastcan.css b/doc/css/fastcan.css
@@ -0,0 +1,21 @@
+.try_examples_button {
+    color: white;
+    background-color: #0054a6;
+    border: none;
+    padding: 5px 10px;
+    border-radius: 10px;
+    margin-bottom: 5px;
+    box-shadow: 0 2px 5px rgba(108,108,108,0.2);
+}
+
+.try_examples_button:hover {
+    background-color: #0066cc;
+    transform: scale(1.02);
+    box-shadow: 0 2px 5px rgba(0, 0, 0, 0.2);
+    cursor: pointer;
+}
+
+.try_examples_button_container {
+    display: flex;
+    justify-content: flex-end;
+}
diff --git a/doc/environment.yml b/doc/environment.yml
@@ -0,0 +1,8 @@
+name: xeus-kernels
+channels:
+  - https://prefix.dev/emscripten-forge-dev
+  - https://prefix.dev/conda-forge
+dependencies:
+  - xeus-python
+  - matplotlib
+  - fastcan
diff --git a/doc/try_examples.json b/doc/try_examples.json
@@ -0,0 +1,3 @@
+{
+    "global_min_height": "400px"
+}
diff --git a/examples/plot_forecasting.py b/examples/plot_forecasting.py
@@ -5,6 +5,9 @@
 
 .. currentmodule:: fastcan.narx
 
+.. note::
+    This example can NOT be run with JupyterLite so far.
+
 In this examples, we will demonstrate how to use :func:`make_narx` to build (nonlinear)
 AutoRegressive (AR) models for time-series forecasting.
 The time series used isthe monthly average atmospheric CO2 concentrations
diff --git a/fastcan/narx/tests/test_narx.py b/fastcan/narx/tests/test_narx.py
@@ -367,7 +367,7 @@ def test_mulit_output_error():
         narx.fit(X, y)
         narx.predict(X, y_init=[1, 1, 1])
 
-    with pytest.raises(ValueError, match="`feat_ids` should not contain rows that.*"):
+    with pytest.raises(ValueError, match=r"`feat_ids` should not contain rows that.*"):
         narx = NARX(
             feat_ids=np.array([[0, 1], [-1, -1]]),
             delay_ids=np.array([[0, 1], [-1, -1]]),
diff --git a/pixi.lock b/pixi.lock
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/rtd-environment.yml b/rtd-environment.yml
diff --git a/scripts/rtd_pre_install.sh b/scripts/rtd_pre_install.sh

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "global_min_height": "400px"`
	`3`	`+}`