update docs

docs/astro.config.mjs

@@ -23,9 +23,9 @@ export default defineConfig({
           items: [
             // Each item here is one entry in the navigation menu.
             { label: "Introduction", link: "guides/introduction" },
-            { label: "Demo", link: "guides/demo/" },
-            { label: "Examples", link: "guides/examples/" },
-            { label: "Installation", link: "guides/installation/" },
+            { label: "Comparison", link: "guides/comparison" },
+            { label: "Examples", link: "guides/examples" },
+            { label: "Installation", link: "guides/installation" },
           ],
         },
         { label: "Documentation", autogenerate: { directory: "references" } },

docs/src/components/PySandboxExample.astro

@@ -1,17 +1,32 @@
 ---
 interface Props {
-  id?: string;
   code: string;
+  target?: string;
+  worker?: boolean;
+  restricted?: boolean;
 }
 
 const { code, target, worker, restricted } = Astro.props;
 ---
 
-<div style="border: 1px solid; padding: 4px;">
-  Output:<div id={target}></div>
+<script src="/pysandbox/coi-serviceworker.js" is:inline></script>
+
+<style>
+  :global(
+      :not(a, strong, em, del, span, input)
+        + :not(a, strong, em, del, span, input, :where(.not-content *))
+    ) {
+    margin-top: 0 !important;
+  }
+</style>
+
+<div style="border: 1px solid; padding: 4px; margin-bottom: 4px;">
+  Output:<div id={target} style="min-height: 500px"></div>
 </div>
 
-<pre>{code}</pre>
+<div id="code-editor" style="margin-bottom: 1.5rem; height: 300px"></div>
+<button class="format">Format Code</button>
+<button class="run" style="margin-left: 4px">Run code</button>
 
 <pysandbox-example
   data-code={code}
@@ -23,6 +38,17 @@ const { code, target, worker, restricted } = Astro.props;
 
 <script>
   import { PyMainThreadSandbox, PyWorkerSandbox } from "pysandbox";
+  import { EditorView, basicSetup } from "codemirror";
+  import { python } from "@codemirror/lang-python";
+  const fixedHeightEditor = EditorView.theme({
+    "&": { height: "300px" },
+    ".cm-scroller": { overflow: "auto" },
+  });
+
+  let editor: EditorView;
+
+  let sandbox: ISandbox;
+  let target: string;
 
   async function getMainThreadSandbox(options) {
     const sandbox = new PyMainThreadSandbox(options);
@@ -36,17 +62,36 @@ const { code, target, worker, restricted } = Astro.props;
     return sandbox;
   }
 
+  async function run(code) {
+    document.getElementById(target).replaceChildren();
+    try {
+      const imports = await sandbox.findImports(code);
+      await sandbox.installPackages(imports, { keep_going: true });
+      await sandbox.exec(code, target);
+    } catch (e) {
+      console.error(e);
+      document.getElementById(target).innerText = String(e);
+    }
+  }
+
   class PySandboxExample extends HTMLElement {
     constructor() {
       super();
+      editor = new EditorView({
+        doc: this.dataset.code,
+        extensions: [basicSetup, python(), fixedHeightEditor],
+        parent: document.getElementById("code-editor"),
+      });
       this.exec();
     }
     async exec() {
-      let sandbox;
+      target = this.dataset.target;
       try {
         if (this.dataset.worker) {
           if (typeof SharedArrayBuffer === "undefined") {
-            throw new Error("Unable to use SharedArrayBuffer due insecure environment.");
+            throw new Error(
+              "Unable to use SharedArrayBuffer due insecure environment.",
+            );
           }
           sandbox = await getWorkerSandbox({
             restricted: this.dataset.restricted,
@@ -56,18 +101,34 @@ const { code, target, worker, restricted } = Astro.props;
             restricted: this.dataset.restricted,
           });
         }
-        const imports = await sandbox.findImports(this.dataset.code);
-        await sandbox.installPackages(imports, { keep_going: true });
-        await sandbox.exec(this.dataset.code, this.dataset.target);
       } catch (e) {
         if (this.dataset.target) {
           globalThis.document.getElementById(this.dataset.target).innerText =
             String(e);
         }
         console.error(e);
       }
+      run(this.dataset.code);
     }
   }
 
   customElements.define("pysandbox-example", PySandboxExample);
+
+  document.querySelectorAll("button.format").forEach((button) => {
+    button.addEventListener("click", async () => {
+      editor.dispatch({
+        changes: {
+          from: 0,
+          to: editor.state.doc.length,
+          insert: await sandbox.formatCode(editor.state.doc.toString()),
+        },
+      });
+    });
+  });
+
+  document.querySelectorAll("button.run").forEach((button) => {
+    button.addEventListener("click", () => {
+      run(editor.state.doc.toString());
+    });
+  });
 </script>

docs/src/content/docs/guides/comparison.md

@@ -0,0 +1,14 @@
+---
+title: Comparison
+description: A comparison of PySandbox and other libraries.
+---
+
+## Pyodide
+
+PySandbox uses [Pyodide](https://github.com/pyodide/pyodide) under the hood. If you are running python code on the main thread, you may enjoy the flexibility of loading Pyodide directly. On the other hand, PySandbox provides a handy `display` utility for showing pyplots and managing other iPython _repr_\*\*\*\* outputs.
+
+Pyodide also doesn't provide web worker support out of the box. If you site is [crossOriginIsolated](https://web.dev/coop-coep/), PySandbox would be able to run the python code in a web worker out of the box.
+
+## PyScript
+
+[PyScript](https://pyscript.net/) is great for quickly configuring a single html page to run python code. However if you are using a JS web-framework (such as React) to build your web application, PySandbox will be able to provide finer grained control via its Javascript based API.

docs/src/content/docs/guides/examples.mdx

@@ -1,8 +1,10 @@
 ---
-title: PySandbox
+title: Examples
 description: Examples of PySandbox.
 ---
 
+Each example below provides a live coding sandbox powered by PySandbox and CodeMirror. You can use the editor to modify the code and to show the new result.
+
 import { LinkCard, CardGrid } from "@astrojs/starlight/components";
 
 <CardGrid>

docs/src/content/docs/guides/installation.md

@@ -1,5 +1,5 @@
 ---
-title: PySandbox
+title: Installation
 description: How to install PySandbox.
 ---
 

docs/src/content/docs/guides/introduction.md

@@ -1,5 +1,5 @@
 ---
-title: PySandbox Introduction
+title: Introduction
 description: What is a PySandbox?
 ---
 

docs/src/content/docs/index.mdx

@@ -8,7 +8,7 @@ hero:
     file: ../../assets/houston.webp
   actions:
     - text: Try it out
-      link: /pysandbox/guides/demo
+      link: /pysandbox/examples/mainthread/example3_seaborn
       icon: right-arrow
       variant: primary
 ---

docs/src/content/docs/references/index.md

@@ -5,7 +5,7 @@ description: References for PySandbox.
 
 The `pysandbox` library exports two classes: `PyMainThreadSandbox` and `PyWorkerSandbox`.
 
-`PyMainThreadSandbox` will execute python code on the main thread while `PyWorkerSandbox` will execute python code in a WebWorker if [crossOriginIsolated](https://web.dev/coop-coep/).
+`PyMainThreadSandbox` will execute python code on the main thread while `PyWorkerSandbox` will execute python code in a web worker if [crossOriginIsolated](https://web.dev/coop-coep/).
 
 Both classes shares an identical interface.
 

docs/src/content/docs/references/library.md

@@ -1,5 +1,5 @@
 ---
-title: PySandbox library
+title: Sandbox Module
 description: References for PySandbox library.
 ---
 

docs/src/content/docs/references/options.md

@@ -1,5 +1,5 @@
 ---
-title: Options
+title: Sandbox Options
 description: References for PySandbox options.
 ---