From 2b4b93fdb53323974ccc13fefd17a2c32a57573c Mon Sep 17 00:00:00 2001 From: Trevor Manz Date: Mon, 23 Sep 2024 12:36:36 -0400 Subject: [PATCH 1/2] docs: Clarify pieces of anywidget project --- README.md | 11 ++++--- docs/src/pages/en/getting-started.mdx | 43 +++++++++++---------------- 2 files changed, 25 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 87119b5a..58d23a62 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

- custom jupyter widgets made easy + reusable widgets made easy

installation . @@ -18,10 +18,11 @@ ## About -**anywidget** uses modern web standards to simplify authoring and distributing -custom Jupyter Widgets. +**anywidget** is both a [**specification**](https://anywidget/dev/en/afm) and +**toolkit** for authoring reusable web-based widgets for interactive computing +environments. -- 🛠️ create widgets **without complicated cookiecutter templates** +- 🛠️ create custom Jupyter Widgets **without complicated cookiecutter templates** - 📚 **publish to PyPI** like any other Python package - 🤖 prototype **within** `.ipynb` or `.py` files - 🚀 run in **Jupyter**, **JupyterLab**, **Google Colab**, **VSCode**, [**marimo**](https://github.com/marimo-team/marimo) and more @@ -46,6 +47,8 @@ conda install -c conda-forge anywidget ## Usage +The easiest way to start developing with **anywidget** is with the Python package. + ```python import anywidget import traitlets diff --git a/docs/src/pages/en/getting-started.mdx b/docs/src/pages/en/getting-started.mdx index 2da2b547..4f76772d 100644 --- a/docs/src/pages/en/getting-started.mdx +++ b/docs/src/pages/en/getting-started.mdx @@ -9,17 +9,18 @@ import CounterButton from "../../components/CounterButton.astro"; ## What is anywidget? -**anywidget** is a Python library that simplifies creating and publishing -custom [Jupyter Widgets](https://ipywidgets.readthedocs.io/en/latest/). -No messy build configuration or complicated cookiecutter templates. - -It is **not** a new interactive widgets framework, but rather -an abstraction for creating custom Jupyter Widgets using modern web standards. +**anywidget** is both a **specification** and **toolkit** for authoring +portable and reusable web-based widgets for interactive computing environments. +As a specification, it defines a standard for widget front-end code. As a +toolkit, it provides tools for authoring widget front-end code according to the +specification, as well as a Python library that simplifies creating and +publishing custom [Jupyter +Widgets](https://ipywidgets.readthedocs.io/en/latest/). ## Key features - 🛠️ Create widgets **without complicated cookiecutter templates** -- 📚 **Publish to PyPI** like any other Python package +- 📚 **Publish Jupyter Widgets to PyPI** like any other Python package - 🤖 Prototype **within** `.ipynb` or `.py` files - 🚀 Run in **Jupyter**, **JupyterLab**, **Google Colab**, **VSCode**, **marimo**, and more - ⚡ Develop with **instant HMR**, like modern web frameworks @@ -27,6 +28,8 @@ an abstraction for creating custom Jupyter Widgets using modern web standards. ## Example +The easiest way to start developing with **anywidget** is with the Python package. + ``` pip install "anywidget[dev]" ``` @@ -69,15 +72,16 @@ What's going on here: Shared state is defined via [traitlets](https://traitlets.readthedocs.io/en/stable/) with the `sync=True` keyword argument. -- `_esm` specifies a **required** [ECMAScript module](https://nodejs.org/api/esm.html) for the widget. +- `_esm` specifies a **required** [Anywidget Front-End Module (AFM)](/en/afm) for the widget. It defines and exports `render`, a function for rendering and initializes dynamic updates for the custom widget. - `_css` specifies an **optional** CSS stylesheet to load for the widget. It can be a full URL or plain text. Styles are loaded in the global scope if using this feature, so take care to avoid naming conflicts. -ECMAScript modules are the offical standard format to package JavaScript code for reuse and are supported -natively across [all major browsers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#javascript.statements.export). -Therefore, dependencies can be imported directly via a fully qualified URL. +The Anywidget Front-End Module (AFM) is a web-standard [ECMAScript module +(ESM)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) +that defines a widget's behavior. It can be authored in a single file using URLs +for third-party dependencies: ```javascript import * as d3 from "https://esm.sh/d3@7"; @@ -90,20 +94,9 @@ function render({ model, el }) { export default { render }; ``` -The `render` function can also (optionally) return a callback that is executed any time the view is -removed from the DOM. This feature is useful when dealing with complex event listeners, subscriptions, -or third-party libraries that require proper teardown. - -```javascript -/** @param {{ model: DOMWidgetModel, el: HTMLElement }} context */ -function render({ model, el }) { - // Create DOM elements and set up subscribers - return () => { - // Optionally cleanup - }; -} -export default { render } -``` +Or produced via [a build step](/en/bundling) to include local dependencies or +use popular JS frameworks (e.g., React, Svelte, Vue). For details on lifecycle +methods and authoring AFM, see the [AFM documentation](/en/afm). ## Progressive Development From b4ec95e8d256c17dbc659a49aab8ba4171a483d6 Mon Sep 17 00:00:00 2001 From: Trevor Manz Date: Mon, 23 Sep 2024 12:50:20 -0400 Subject: [PATCH 2/2] Add section on relationship with jupyter widgets --- docs/src/pages/en/getting-started.mdx | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/src/pages/en/getting-started.mdx b/docs/src/pages/en/getting-started.mdx index 4f76772d..5f757c56 100644 --- a/docs/src/pages/en/getting-started.mdx +++ b/docs/src/pages/en/getting-started.mdx @@ -10,9 +10,9 @@ import CounterButton from "../../components/CounterButton.astro"; ## What is anywidget? **anywidget** is both a **specification** and **toolkit** for authoring -portable and reusable web-based widgets for interactive computing environments. -As a specification, it defines a standard for widget front-end code. As a -toolkit, it provides tools for authoring widget front-end code according to the +reusable web-based widgets for interactive computing environments. As a +specification, it defines a standard for widget front-end code. As a toolkit, +it provides tools for authoring widget front-end code according to the specification, as well as a Python library that simplifies creating and publishing custom [Jupyter Widgets](https://ipywidgets.readthedocs.io/en/latest/). @@ -165,3 +165,14 @@ and publishing a package on PyPI. allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen > + +## Relationship to Jupyter Widgets + +**anywidget** began as a modern alternative for authoring custom Jupyter +Widgets and is now the [recommended +method](https://github.com/jupyter-widgets/widget-cookiecutter) for creating +them. The project has since grown in scope as [AFM](/en/afm) has been adopted +by platforms beyond Python and Jupyter. While maintaining its primary focus on +Jupyter Widgets, **anywidget** now enables the creation of custom widgets for a +variety of interactive computing environments (including Deno, R, and entirely +in the browser).