Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
186 lines (127 loc) · 5.57 KB

CONTRIBUTING.md

File metadata and controls

186 lines (127 loc) · 5.57 KB

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.8
  • nodejs >=20,<21

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