Contributing#

The final, user-facing products of jupyterlite-pyodide-kernel are:

Preparing for a release, however, requires a number of intermediate steps.

Recommended: Start with the (almost) single-line quick start script, and watch what it does to files on disk and in the terminal log.

Quick Start#

Prerequisites#

  • git

  • python >=3.10

  • nodejs >=22

Setup#

git clone https://github.com/jupyterlite/pyodide-kernel
cd pyodide-kernel
npm run quickstart

Serve#

jlpm serve

provides

requires

a development web server

install
build
demo

Serve the build/ directory as http://127.0.0.1:8000, which contains:

  • docs-app/ just the built JupyterLite

  • docs/ the full documentation website

  • reports/ built reports from tests and static analysis

Individual Steps#

npm run quickstart will, in the correct order:

  • clean out any pre-existing built artifacts and caches

  • ensure local Python and NodeJS has all required dependencies for development

  • build the underlying JS/CSS assets that will be served to the browser in a JupyterLite site

  • build distributions ready for on pypi.org and npmjs.org

  • a minimal JupyterLite demo site with

    • pyodide-core, a lightweight Pyodide distribution (5mb vs 250mb)

    • the @jupyter-widget/jupyterlab-manager extension enabled

  • the documentation website (including the demo)

  • test the code and generate HTML reports

Dependencies#

Python#

python -m pip install -e .[dev,test,docs]

provides

requires

run after changing

jlpm

prerequisites

pyproject.toml

The above installs JupyterLab, which provides the jlpm command, a pre-packaged version of yarn, and is used instead of npm from here on out.

JavaScript#

jlpm

provides

requires

run after changing

node_modules

install

package.json

Run this after changing the dependencies or devDependencies of any package.json

This will update the yarn.lock with a reproducible solution to the NodeJS build tools and static assets that will be served on the website.

Run this after changing pyproject.toml.

Build#

jlpm build
# or
jlpm build:prod

provides

requires

run after changing

packages/*/lib/*.js
jupyterlab_pyodide_kernel/labextension

install

packages/*/src/**/*.tsx?
packages/*/style/**/*.*

Build and install development versions of the JS packages and lab extension.

Distributions#

jlpm dist

provides

requires

run after changing

dist

build

packages/*
jupyterlite_pyodide_kernel/*

Build distributions for pypi.org and npmjs.org.

Test#

jlpm test

provides

requires

run after changing

dist

build

jupyterlite_pyodide_kernel/*

Run JS and Python tests.

Sites#

jlpm docs

Builds both sites described below.

Demo#

jlpm docs:lite

provides

requires

run after changing

build/docs-app

build

packages/*
jupyterlite_pyodide_kernel/*
examples/*

Build a minimal JupyterLite demo site.

As a JupyterLite “server” extension, @jupyterlite/pyodide-kernel will have no effect on a “vanilla” JupyterLab installation, so this is the closest experience to jupyter labextension develop currently available.

Documentation#

jlpm docs:sphinx

provides

requires

run after changing

build/docs

demo

packages/*
jupyterlite_pyodide_kernel/*
examples/*
docs

Build a site in build/docs with Sphinx which includes a copy of the JupyterLite site.

Clean#

jlpm clean:all

provides

requires

run after

-

install

anything that seems out-of-date

Removes all built assets, caches, etc. node_modules won’t be cleaned out

Cleaner#

jlpm cache clean
rm -rf node_modules

Making a new release of jupyterlite-pyodide-kernel#

Automated Releases with jupyter_releaser#

The recommended way to make a release is to use jupyter_releaser.

This repository contains the two workflows located under https://github.com/jupyterlite/pyodide-kernel/actions:

  • Step 1: Prep Release

  • Step 2: Publish Release

Specifying a version spec#

The next version spec is supported and will bump the packages as follows. For example:

  • 0.1.0a0 -> 0.1.0a1

  • 0.1.0b7 -> 0.1.0b8

  • 0.1.0 -> 0.1.1

You can also specify the Python version directly as the version_spec when using the releaser workflows. For example:

  • 0.1.0b8

  • 0.1.1

  • 1.2.0rc0