docs(tutorial): deploy jupyterlite

.github/workflows/ibis-docs-main.yml

@@ -45,6 +45,9 @@ jobs:
       - name: build docs
         run: nix develop --ignore-environment --keep HOME -c just docs-render
 
+      - name: build jupyterlite
+        run: nix develop --ignore-environment --keep HOME -c just build-jupyterlite --debug
+
       - name: check that all frozen computations were done before push
         run: git diff --exit-code --stat
 

.github/workflows/ibis-docs-pr.yml

@@ -47,6 +47,9 @@ jobs:
       - name: build docs
         run: nix develop --ignore-environment --keep HOME -c just docs-render
 
+      - name: build docs
+        run: nix develop --ignore-environment --keep HOME -c just build-jupyterlite --debug
+
       - name: check that all frozen computations were done before push
         run: git diff --exit-code --stat
 

.gitignore

@@ -147,3 +147,7 @@ docs/**/.jupyter_cache
 # quarto generated files
 docs/posts-listing.json
 docs/posts.feed-full-staged
+
+# jupyterlite stuff
+.jupyterlite.doit.db
+content/*.ipynb

content/runtime.txt

@@ -0,0 +1 @@
+3.11

docs/_quarto.yml

@@ -97,6 +97,8 @@ website:
       - posts.qmd
       - release_notes.qmd
       - sidebar:contribute
+      - text: "Try Ibis live"
+        file: ./jupyterlite/index.html
 
   sidebar:
     - id: ""

docs/jupyter_lite_config.json

@@ -0,0 +1,7 @@
+{
+  "PipliteAddon": {
+    "piplite_urls": [
+      "https://duckdb.github.io/duckdb-pyodide/wheels/duckdb-0.10.2-cp311-cp311-emscripten_3_1_46_wasm32.whl"
+    ]
+  }
+}

docs/overrides.json

@@ -0,0 +1,5 @@
+{
+  "jupyter-config-data": {
+    "defaultKernelName": "Python (Pyodide)"
+  }
+}

docs/tutorials/getting_started.qmd

@@ -4,7 +4,9 @@ This is a quick tour of some basic commands and usage patterns, just to get your
 
 ## Install Ibis
 
-{{< include ../_tabsets/install_default.qmd >}}
+```bash
+pip install 'ibis-framework[duckdb]'
+```
 
 ## Create a database file
 

justfile

@@ -162,17 +162,37 @@ docs-preview:
 
 # regen api and preview docs
 docs-api-preview:
+    just build-jupyterlite
     just docs-apigen --verbose
     quarto preview docs
 
 # deploy docs to netlify
 docs-deploy:
     quarto publish --no-prompt --no-browser --no-render netlify docs
 
+# build jupyterlite deployment
+build-jupyterlite *args:
+    #!/usr/bin/env bash
+    mkdir -p content
+    quarto convert docs/tutorials/getting_started.qmd --output content/getting_started.ipynb
+    mkdir -p docs/_output/jupyterlite
+    jupyter lite build \
+        --force \
+        --no-libarchive \
+        --config docs/jupyter_lite_config.json \
+        --settings-overrides docs/overrides.json \
+        --output-dir docs/_output/jupyterlite \
+        --contents content
+    # jupyter lite build can copy from the nix store, and preserves the
+    # original write bit; without this the next run of this rule will result in
+    # a permission error when the build tries to remove existing files
+    chmod -R u+w docs/_output/jupyterlite
+
 # run the entire docs build pipeline
 docs-build-all:
     just docs-apigen --verbose
     just docs-render
+    just build-jupyterlite
     just checklinks docs/_output --offline --no-progress
 
 # open chat