Update numbl links and tidy copy
7 changed files+29−36
README.mdmodified+16−17View file
@@ -1,22 +1,22 @@
11 # jupyterlite-numbl-kernel
22
3-Run [**numbl**](https://github.com/flatironinstitute/numbl) — numerical
4-computing with **MATLAB syntax** — in
5-[JupyterLite](https://jupyterlite.readthedocs.io/) notebooks, **entirely in
6-the browser**, with no server, no kernel process, and nothing for the reader
7-to install.
3+Run [**numbl**](https://numbl.org), numerical computing with **MATLAB
4+syntax**, in [JupyterLite](https://jupyterlite.readthedocs.io/) notebooks,
5+**entirely in the browser**, with no server, no kernel process, and nothing
6+for the reader to install.
87
98 numbl is an open-source numerical-computing engine, written in TypeScript,
10-that uses MATLAB syntax — so `.m` code runs unchanged. This kernel runs a
9+that uses MATLAB syntax, so `.m` code runs unchanged. This kernel runs a
1110 numbl session in a Web Worker in the page: variables persist across cells,
1211 console output streams into the running cell, plots render as figures in cell
1312 outputs (including interactive 3-D), the `mip` package manager can install
1413 numbl packages from GitHub, and `.m` files next to the notebook are part of
15-the workspace (named functions, called from cells) — all client-side.
14+the workspace (named functions, called from cells). Everything runs
15+client-side.
1616
1717 **Demo site:**
1818 <https://concept-collection.github.io/jupyterlite-numbl-kernel/> (deployed
19-from this repo via GitHub Pages — see `.github/workflows/deploy.yml`)
19+from this repo via GitHub Pages; see `.github/workflows/deploy.yml`)
2020
2121 ## Why
2222
@@ -30,7 +30,7 @@ require a licensed product behind a server just runs in the tab.
3030
3131 Three small pieces, all in this repo:
3232
33-- **Kernel** (`src/kernel.ts`) — implements JupyterLite's `BaseKernel` from
33+- **Kernel** (`src/kernel.ts`): implements JupyterLite's `BaseKernel` from
3434 `@jupyterlite/services`. Before each `execute_request`, `.m` files in the
3535 notebook's directory (read via the JupyterLite contents manager) are
3636 synced into the numbl session; the cell source then runs against the
@@ -39,12 +39,12 @@ Three small pieces, all in this repo:
3939 Output streams back as `stream` messages; the run's plot instructions are
4040 published as `display_data` with the mime type
4141 `application/vnd.numbl.figure+json`.
42-- **Figure renderer** (`src/mime.tsx`) — a JupyterLab mime renderer for that
42+- **Figure renderer** (`src/mime.tsx`): a JupyterLab mime renderer for that
4343 mime type: it replays the instructions through numbl's figures reducer and
4444 mounts numbl's React `FigureView` (from `numbl/graphics`). Outputs are
4545 plain JSON, so saved notebooks re-render wherever the extension is
4646 installed.
47-- **Kernel registration** (`src/index.ts`) — registers the kernelspec with
47+- **Kernel registration** (`src/index.ts`): registers the kernelspec with
4848 JupyterLite's `IKernelSpecs`.
4949
5050 ## Build a site with it
@@ -52,7 +52,7 @@ Three small pieces, all in this repo:
5252 ```bash
5353 pip install jupyterlite-core jupyterlite-numbl-kernel
5454 jupyter lite build --contents my-notebooks --output-dir dist
55-# dist/ is a static site — serve it anywhere
55+# dist/ is a static site; serve it anywhere
5656 ```
5757
5858 The `demo/` directory in this repo contains the demo site sources
@@ -72,7 +72,7 @@ JupyterLite caches content in two layers that both defeat redeploys:
7272 Since this is a demo, `demo/jupyter-lite.json` neutralizes both: it uses
7373 JupyterLite's in-memory storage (so every reload re-seeds the latest
7474 deployed notebooks) and disables the service-worker plugin (which the numbl
75-kernel doesn't need — it reads content on the main thread, not via the
75+kernel doesn't need, since it reads content on the main thread, not via the
7676 service worker's kernel drive):
7777
7878 ```json
@@ -109,7 +109,7 @@ persist across reloads.
109109 - **Figures are per-cell** (like inline matplotlib): each cell renders the
110110 figures its own commands produce; `hold on` does not span cells.
111111 - **Named function definitions are not supported inside cells** (a numbl
112- REPL limitation) — anonymous functions work; named functions belong in
112+ REPL limitation): anonymous functions work, and named functions belong in
113113 `.m` files next to the notebook (see `demo/content/statsutils.m`), which
114114 this kernel syncs into the session automatically.
115115 - The `.m`-file sync is **one-way**: deleting a `.m` file from the file
@@ -119,8 +119,7 @@ persist across reloads.
119119 - **uihtml** components render display-only; the MATLAB↔HTML event bridge
120120 is not wired into outputs yet.
121121 - numbl itself is not MATLAB: it covers a large, tested subset of the
122- language and toolbox surface. See the
123- [numbl repo](https://github.com/flatironinstitute/numbl) for scope.
122+ language and toolbox surface. See [numbl](https://numbl.org) for scope.
124123
125124 ## Development
126125
@@ -147,7 +146,7 @@ python -m http.server -d demo/_output 8000
147146
148147 ## License
149148
150-Apache-2.0. Built on [numbl](https://github.com/flatironinstitute/numbl) and
149+Apache-2.0. Built on [numbl](https://numbl.org) and
151150 the [JupyterLite](https://github.com/jupyterlite/jupyterlite) kernel API;
152151 scaffolding follows the
153152 [jupyterlite/echo-kernel](https://github.com/jupyterlite/echo-kernel)
demo/content/01-intro.ipynbmodified+3−6View file
@@ -4,7 +4,7 @@
44 "cell_type": "markdown",
55 "id": "intro-title",
66 "metadata": {},
7- "source": "# numbl — MATLAB syntax, entirely in your browser\n\nThis notebook runs on the **numbl kernel for JupyterLite**. Every cell executes\nin a Web Worker in *your* browser tab — there is no server and no kernel\nprocess behind this page, and nothing to install.\n\n[numbl](https://github.com/flatironinstitute/numbl) is an open-source\nnumerical-computing engine written in TypeScript. It uses MATLAB syntax, so\n`.m` code runs unchanged.\n\nRun the cells below with **Shift+Enter**."
7+ "source": "# numbl: MATLAB syntax, entirely in your browser\n\nThis notebook runs on the **numbl kernel for JupyterLite**. Every cell executes\nin a Web Worker in *your* browser tab, with no server and no kernel process\nbehind this page, and nothing to install.\n\n[numbl](https://numbl.org) is an open-source numerical-computing engine\nwritten in TypeScript. It uses MATLAB syntax, so `.m` code runs unchanged.\n\nRun the cells below with **Shift+Enter**."
88 },
99 {
1010 "cell_type": "code",
@@ -66,7 +66,7 @@
6666 {
6767 "cell_type": "markdown",
6868 "id": "1e814d6c",
69- "source": "## Named functions live in `.m` files\n\nnumbl's cells work like the MATLAB console: you can't define a *named*\nfunction directly in a cell. Instead, put it in a `.m` file next to the\nnotebook — this kernel syncs `.m` files from the file browser into the\nsession before every cell runs, so functions defined there are callable\nimmediately, and edits take effect the next time you run a cell.\n\nThis notebook ships with [statsutils.m](./statsutils.m) — open it, and try\nediting it (e.g. add a `median` field) while the cell below is still there.",
69+ "source": "## Named functions live in `.m` files\n\nnumbl's cells work like the MATLAB console: you can't define a *named*\nfunction directly in a cell. Instead, put it in a `.m` file next to the\nnotebook. This kernel syncs `.m` files from the file browser into the\nsession before every cell runs, so functions defined there are callable\nimmediately, and edits take effect the next time you run a cell.\n\nThis notebook ships with [statsutils.m](./statsutils.m); open it and try\nediting it (e.g. add a `median` field) while the cell below is still there.",
7070 "metadata": {}
7171 },
7272 {
@@ -81,10 +81,7 @@
8181 "cell_type": "markdown",
8282 "id": "intro-next",
8383 "metadata": {},
84- "source": [
85- "Next: [plotting](./02-plotting.ipynb) and\n",
86- "[installing packages](./03-packages.ipynb) — both also fully client-side."
87- ]
84+ "source": "Next: [plotting](./02-plotting.ipynb) and\n[installing packages](./03-packages.ipynb), both also fully client-side."
8885 }
8986 ],
9087 "metadata": {
demo/content/02-plotting.ipynbmodified+2−5View file
@@ -4,7 +4,7 @@
44 "cell_type": "markdown",
55 "id": "plot-title",
66 "metadata": {},
7- "source": "# Plotting\n\nnumbl's plotting commands render through its figure renderer, straight\ninto the cell output — no display server involved. 3-D figures are\ninteractive (drag to rotate).\n\nFigures are per-cell, like inline matplotlib: each cell renders the figures\nits own commands produce."
7+ "source": "# Plotting\n\nnumbl's plotting commands render through its figure renderer, straight\ninto the cell output, with no display server involved. 3-D figures are\ninteractive (drag to rotate).\n\nFigures are per-cell, like inline matplotlib: each cell renders the figures\nits own commands produce."
88 },
99 {
1010 "cell_type": "code",
@@ -53,10 +53,7 @@
5353 "id": "plot-surf",
5454 "metadata": {},
5555 "outputs": [],
56- "source": [
57- "surf(peaks(40));\n",
58- "title('peaks surface — drag to rotate');"
59- ]
56+ "source": "surf(peaks(40));\ntitle('peaks surface (drag to rotate)');"
6057 }
6158 ],
6259 "metadata": {
demo/content/03-packages.ipynbmodified+1−1View file
@@ -4,7 +4,7 @@
44 "cell_type": "markdown",
55 "id": "pkg-title",
66 "metadata": {},
7- "source": "# Installing packages — still no server\n\nnumbl ships with `mip`, a package manager for numbl packages. Packages are\nfetched from GitHub releases and cached in your browser's IndexedDB, so the\ndownload happens once.\n\nThe first cell you run in a session also bootstraps the engine, so expect a\nshort delay (progress is printed)."
7+ "source": "# Installing packages (still no server)\n\nnumbl ships with `mip`, a package manager for numbl packages. Packages are\nfetched from GitHub releases and cached in your browser's IndexedDB, so the\ndownload happens once.\n\nThe first cell you run in a session also bootstraps the engine, so expect a\nshort delay (progress is printed)."
88 },
99 {
1010 "cell_type": "code",
demo/content/statsutils.mmodified+1−1View file
@@ -1,7 +1,7 @@
11 function s = statsutils(x)
22 % Workspace helper: named functions like this live in a plain .m file next
33 % to the notebook (numbl's REPL cells can't define named functions
4-% directly). Edit this file and rerun a cell — numbl picks up the change.
4+% directly). Edit this file and rerun a cell; numbl picks up the change.
55 s.mean = mean(x);
66 s.std = std(x);
77 s.range = max(x) - min(x);
src/kernel.tsmodified+5−5View file
@@ -10,8 +10,8 @@ import type { NumblSession } from 'numbl/browser';
1010 export const FIGURE_MIME = 'application/vnd.numbl.figure+json';
1111
1212 /**
13- * A JupyterLite kernel that runs numbl — a MATLAB-syntax numerical
14- * computing engine — entirely in the browser.
13+ * A JupyterLite kernel that runs numbl (a MATLAB-syntax numerical
14+ * computing engine) entirely in the browser.
1515 *
1616 * Each kernel owns one numbl session (a Web Worker managed by numbl):
1717 * variables persist across cells, console output streams to the running
@@ -22,7 +22,7 @@ export const FIGURE_MIME = 'application/vnd.numbl.figure+json';
2222 * Before every execution, `.m` files sitting next to the notebook (in the
2323 * JupyterLite contents) are synced into the session, so named functions can
2424 * be defined in the file browser, edited in the Jupyter editor, and called
25- * from cells — numbl rescans the working directory on each execution, so
25+ * from cells. numbl rescans the working directory on each execution, so
2626 * edits apply on the next run. The sync is one-way and additive: deleting a
2727 * `.m` file leaves its function defined until the kernel restarts.
2828 */
@@ -61,7 +61,7 @@ export class NumblKernel extends BaseKernel {
6161 help_links: [
6262 {
6363 text: 'numbl',
64- url: 'https://github.com/flatironinstitute/numbl'
64+ url: 'https://numbl.org'
6565 }
6666 ]
6767 };
@@ -105,7 +105,7 @@ export class NumblKernel extends BaseKernel {
105105 data: {
106106 [FIGURE_MIME]: { version: 1, plotInstructions: instructions },
107107 'text/plain':
108- '<numbl figure — install jupyterlite-numbl-kernel to render>'
108+ '<numbl figure (install jupyterlite-numbl-kernel to render)>'
109109 },
110110 metadata: {}
111111 });
src/mime.tsxmodified+1−1View file
@@ -18,7 +18,7 @@ export const FIGURE_MIME = 'application/vnd.numbl.figure+json';
1818
1919 /**
2020 * Render one cell's plot instructions: replay them through numbl's figures
21- * reducer (from an empty state — figures are per-cell, like inline
21+ * reducer (from an empty state; figures are per-cell, like inline
2222 * matplotlib) and mount numbl's React figure renderer for each resulting
2323 * figure. Outputs are plain JSON, so saved notebooks re-render on reload
2424 * wherever this extension is installed.