Thanks for contributing to JupyterLite!
We follow Project Jupyter’s Code of Conduct for a friendly and welcoming collaborative environment.
Get the Code¶
git clone https://github.com/jupyterlite/jupyterlite
if you don’t have
gityet, you might be able to use the instructions below to get it
Various package managers on different operating systems provide these.
A recommended approach for any platform is to install Mambaforge and use the Binder environment description checked into the repo.mamba env update --file .binder/environment.yml mamba activate jupyterlite-dev
For speed, in GitHub Actions,
nodejs are installed directly. Provided you
already have these, to install the full development stack:
python -m pip install -r requirements-docs.txt -r requirements-lint.txt
doit handles the full software lifecycle, spanning
between different nested tasks, usually as files that change on disk.
To see all of the tasks available, use the
doit list --all --status
To get information about a specific task, use the info
info action with the task
name from the first column of
doit info build:js:app:retro
Task and Action Defaults¶
doit action is
run which… runs the named tasks.
The default tasks are
docs:app:build, so the following are
doit doit lint build docs:app:build doit run lint build docs:app:build
On Linux and MacOS,
doit auto (which can also accept task names) will watch all files
and perform any dependent tasks, then reload the tasks, useful for rapidly seeing
doit lintwhich may change source files. This can be confusing to IDEs (or the
watch:jstasks) that might be performing their own watching, or run up against file system limits.
The JupyterLite core JS development workflow builds:
a ready-to-serve, empty website with:
lab/index.htmland supporting assets
retro/*/index.htmland supporting assets (for
common configuration tools
TBD: a set of component tarballs distributed on
npmjs.com. See #7.
a set of
@jupyterlitenamespace, , written in TypeScript
some un-compiled, vanilla JS for very early-loading utilities
TODO: fix this, perhaps with jsdoc tags
While most of the scripts below will be run (in the correct order based on changes) by
doit, the following scripts (defined in
package.json) are worth highlighting.
Most of the development tasks can be run with one command:
To build development assets:
To build production assets:
These are not real server solutions, but they will serve all of the assets types (including
.wasm) correctly for JupyterLite development, testing, and demo purposes.
To serve with
scripts/serve.js, based on Node.js’s
To serve with Python’s built-in
http.server module (requires
Run Unit Tests¶
yarn build:test yarn test
Lab Extension development¶
TBD: describe how the
@jupyterlite/labextensionworks with e.g. real serverextensions
(Browser) Python Development¶
TBD: describe successor to
pyolite, patches, etc. See #151.
(Server) Python Development¶
After all the
yarn-related work has finished, the terminal-compatible python uses the
npm-compatible tarball of
app to build new sites combined with original user
PYTEST_ARGS can be passed as a (gross) JSON string:
PYTEST_ARGS='["-s", "-x", "--ff"]' doit test:py:jupyterlite
Several tasks invoke the
jupyter lite CLI, which is further described in the main docs
The documentation site, served on jupyterlite.rtfd.io, uses information from different
parts of the software lifecycle (e.g. contains an archive of the built
so using the doit tools are recommended.
sphinx-buildarguments are set by the
SPHINX_ARGSenvironment variable. For example to fail on all warnings (the configuration for the ReadTheDocs build):SPHINX_ARGS='["-W"]' doit docs
This also respects the
SPHINX_ARGSvariable. If working on the theme layer,
SPHINX_ARGS='["-a", "-j8"]'is recommended, as by default static assets are not included in the calculation of what needs to be updated.
JupyterLite features and bug fixes start as issues on GitHub.
JupyterLite features and fixes become real as pull requests.
Pull requests are a great place to discuss work-in-progress, but it is highly recommended to create an issue before starting work so the community can weigh in on choices.
Fork the repo
Make a new branch off
Push to your fork
Start the pull request
gitCLI should offer you a link, as will the GitHub web UI
reference one or more issue so those that are interested can find your work
adding magic strings like
fixes #123help tie the collaboration history together
Wait for continuous integration
If stuff breaks, fix it or ask for help!
Each pull request is built and deployed on ReadTheDocs. You can view the live preview site by clicking on the ReadTheDocs check:
Additionally, several build artifacts are available from the each run on the Actions page, including:
an app archive ready to be used as the input to the
jupyter liteCLI with all the demo content and supporting extensions.
You must be logged in to GitHub to download these.
TBD: See #121.