From 147d7fb0c55fca0399f0d94b50d787c6f37d7ceb Mon Sep 17 00:00:00 2001 From: Jack Zhao Date: Tue, 19 Sep 2023 21:32:24 +0000 Subject: [PATCH] update docs --- docs/astro.config.mjs | 6 +- docs/public/coi-serviceworker.min.js | 2 + docs/src/components/PyCodeEditor.astro | 82 -------------------- docs/src/components/PySandboxExample.astro | 79 ++++++++++++++++--- docs/src/content/docs/guides/comparison.md | 14 ++++ docs/src/content/docs/guides/demo.mdx | 30 ------- docs/src/content/docs/guides/examples.mdx | 4 +- docs/src/content/docs/guides/installation.md | 2 +- docs/src/content/docs/guides/introduction.md | 2 +- docs/src/content/docs/guides/pysandbox.md | 11 --- docs/src/content/docs/index.mdx | 2 +- docs/src/content/docs/references/index.md | 2 +- docs/src/content/docs/references/library.md | 2 +- docs/src/content/docs/references/options.md | 2 +- 14 files changed, 98 insertions(+), 142 deletions(-) create mode 100644 docs/public/coi-serviceworker.min.js delete mode 100644 docs/src/components/PyCodeEditor.astro create mode 100644 docs/src/content/docs/guides/comparison.md delete mode 100644 docs/src/content/docs/guides/demo.mdx delete mode 100644 docs/src/content/docs/guides/pysandbox.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 34cc780..5cf238c 100644 --- a/docs/astro.config.mjs +++ b/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" } }, diff --git a/docs/public/coi-serviceworker.min.js b/docs/public/coi-serviceworker.min.js new file mode 100644 index 0000000..34e6e16 --- /dev/null +++ b/docs/public/coi-serviceworker.min.js @@ -0,0 +1,2 @@ +/*! coi-serviceworker v0.1.7 - Guido Zuidhof and contributors, licensed under MIT */ +let coepCredentialless=!1;"undefined"==typeof window?(self.addEventListener("install",(()=>self.skipWaiting())),self.addEventListener("activate",(e=>e.waitUntil(self.clients.claim()))),self.addEventListener("message",(e=>{e.data&&("deregister"===e.data.type?self.registration.unregister().then((()=>self.clients.matchAll())).then((e=>{e.forEach((e=>e.navigate(e.url)))})):"coepCredentialless"===e.data.type&&(coepCredentialless=e.data.value))})),self.addEventListener("fetch",(function(e){const r=e.request;if("only-if-cached"===r.cache&&"same-origin"!==r.mode)return;const s=coepCredentialless&&"no-cors"===r.mode?new Request(r,{credentials:"omit"}):r;e.respondWith(fetch(s).then((e=>{if(0===e.status)return e;const r=new Headers(e.headers);return r.set("Cross-Origin-Embedder-Policy",coepCredentialless?"credentialless":"require-corp"),coepCredentialless||r.set("Cross-Origin-Resource-Policy","cross-origin"),r.set("Cross-Origin-Opener-Policy","same-origin"),new Response(e.body,{status:e.status,statusText:e.statusText,headers:r})})).catch((e=>console.error(e))))}))):(()=>{const e={shouldRegister:()=>!0,shouldDeregister:()=>!1,coepCredentialless:()=>(window.chrome!==undefined||window.netscape!==undefined),doReload:()=>window.location.reload(),quiet:!1,...window.coi},r=navigator;r.serviceWorker&&r.serviceWorker.controller&&(r.serviceWorker.controller.postMessage({type:"coepCredentialless",value:e.coepCredentialless()}),e.shouldDeregister()&&r.serviceWorker.controller.postMessage({type:"deregister"})),!1===window.crossOriginIsolated&&e.shouldRegister()&&(window.isSecureContext?r.serviceWorker&&r.serviceWorker.register(window.document.currentScript.src).then((s=>{!e.quiet&&console.log("COOP/COEP Service Worker registered",s.scope),s.addEventListener("updatefound",(()=>{!e.quiet&&console.log("Reloading page to make use of updated COOP/COEP Service Worker."),e.doReload()})),s.active&&!r.serviceWorker.controller&&(!e.quiet&&console.log("Reloading page to make use of COOP/COEP Service Worker."),e.doReload())}),(r=>{!e.quiet&&console.error("COOP/COEP Service Worker failed to register:",r)})):!e.quiet&&console.log("COOP/COEP Service Worker not registered, a secure context is required."))})(); \ No newline at end of file diff --git a/docs/src/components/PyCodeEditor.astro b/docs/src/components/PyCodeEditor.astro deleted file mode 100644 index 3efd560..0000000 --- a/docs/src/components/PyCodeEditor.astro +++ /dev/null @@ -1,82 +0,0 @@ ---- -interface Props { - code?: string; -} - -const { code } = Astro.props; ---- - - - -
-
- - - - - diff --git a/docs/src/components/PySandboxExample.astro b/docs/src/components/PySandboxExample.astro index 04fb5aa..a9554b8 100644 --- a/docs/src/components/PySandboxExample.astro +++ b/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; --- -
- Output:
+ + + + +
+ Output:
-
{code}
+
+ + 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,9 +101,6 @@ 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 = @@ -66,8 +108,27 @@ const { code, target, worker, restricted } = Astro.props; } 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()); + }); + }); diff --git a/docs/src/content/docs/guides/comparison.md b/docs/src/content/docs/guides/comparison.md new file mode 100644 index 0000000..34ce318 --- /dev/null +++ b/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. diff --git a/docs/src/content/docs/guides/demo.mdx b/docs/src/content/docs/guides/demo.mdx deleted file mode 100644 index 046da19..0000000 --- a/docs/src/content/docs/guides/demo.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: PySandbox -description: A demo of PySandbox. ---- - -import PyCodeEditor from "../../../components/PyCodeEditor.astro"; - - diff --git a/docs/src/content/docs/guides/examples.mdx b/docs/src/content/docs/guides/examples.mdx index 58c776b..0fa3509 100644 --- a/docs/src/content/docs/guides/examples.mdx +++ b/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"; diff --git a/docs/src/content/docs/guides/installation.md b/docs/src/content/docs/guides/installation.md index 8a6a7bb..2cbb13d 100644 --- a/docs/src/content/docs/guides/installation.md +++ b/docs/src/content/docs/guides/installation.md @@ -1,5 +1,5 @@ --- -title: PySandbox +title: Installation description: How to install PySandbox. --- diff --git a/docs/src/content/docs/guides/introduction.md b/docs/src/content/docs/guides/introduction.md index ecc24c2..0fa46fc 100644 --- a/docs/src/content/docs/guides/introduction.md +++ b/docs/src/content/docs/guides/introduction.md @@ -1,5 +1,5 @@ --- -title: PySandbox Introduction +title: Introduction description: What is a PySandbox? --- diff --git a/docs/src/content/docs/guides/pysandbox.md b/docs/src/content/docs/guides/pysandbox.md deleted file mode 100644 index b7eebbb..0000000 --- a/docs/src/content/docs/guides/pysandbox.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: PySandbox -description: A guide to PySandbox. ---- - -Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. -Writing a good guide requires thinking about what your users are trying to do. - -## Further reading - -- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 7847598..7a80d05 100644 --- a/docs/src/content/docs/index.mdx +++ b/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 --- diff --git a/docs/src/content/docs/references/index.md b/docs/src/content/docs/references/index.md index 6c1ef79..2d943d7 100644 --- a/docs/src/content/docs/references/index.md +++ b/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. diff --git a/docs/src/content/docs/references/library.md b/docs/src/content/docs/references/library.md index c6d03a2..d40dd9e 100644 --- a/docs/src/content/docs/references/library.md +++ b/docs/src/content/docs/references/library.md @@ -1,5 +1,5 @@ --- -title: PySandbox library +title: Sandbox Module description: References for PySandbox library. --- diff --git a/docs/src/content/docs/references/options.md b/docs/src/content/docs/references/options.md index 3302077..9081eeb 100644 --- a/docs/src/content/docs/references/options.md +++ b/docs/src/content/docs/references/options.md @@ -1,5 +1,5 @@ --- -title: Options +title: Sandbox Options description: References for PySandbox options. ---