Install uv.
To register the current uv-managed Python environment with JupyterLab, run
uv run python -m ipykernel install --user --name "lonboard"
JupyterLab is an included dev dependency, so to start JupyterLab you can run
ANYWIDGET_HMR=1 uv run jupyter lab
Note that ANYWIDGET_HMR=1 is necessary to turn on "hot-reloading", so that any
updates you make in JavaScript code are automatically updated in your notebook.
Then you should see a tile on the home screen that lets you open a Jupyter Notebook in the lonboard environment. You should also be able to open up an example notebook from the examples/ folder.
Requirements:
Install module dependencies:
npm installWe use ESBuild to bundle into an ES Module, which the Jupyter Widget will then load at runtime. The configuration for ESBuild can be found in build.mjs. To start watching for changes in the /src folder and automatically generate a new build, use:
npm run build:watchTo use custom environment variables, copy the example environment file:
cp .env.example .envThis file contains the list of environment variables for the JavaScript component, and the build task will use them when available.
Note: .env is in .gitignore and should never be committed.
All models on the TypeScript side are combined into a single entry point, which is compiled by ESBuild and loaded by the Python Map class. (Refer to the _esm key on the Map class, which tells Jupyter/ipywidgets where to load the JavaScript bundle.)
Anywidget and its dependency ipywidgets handles the serialization from Python into JS, automatically keeping each side in sync.
State management is implemented using XState. The app is instrumented with Stately Inspector, and the use of the VS Code extension is highly recommended.
Push a new tag to the main branch of the format v*. A new version will be published to PyPI automatically.
The documentation website is generated with mkdocs and mkdocs-material. You can serve the docs website locally with
uv run mkdocs serve
Publishing documentation happens automatically via CI when a new tag is published of the format v*. It can also be triggered manually through the Github Actions dashboard on this page. Note that publishing docs manually is not advised if there have been new code additions since the last release as the new functionality will be associated in the documentation with the tag of the previous release. In this case, prefer publishing a new patch or minor release, which will publish both a new Python package and the new documentation for it.