Thanks for contributing to JupyterLite!
We follow Project Jupyter's Code of Conduct for a friendly and welcoming collaborative environment.
git clone https://github.com/jupyterlite/jupyterlite
if you don't have
git
yet, you might be able to use the instructions below to get it
You'll need:
git
nodejs >=12
yarn <2
python >=3.8
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, python
and 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
JavaScript to documentation building and link checking. It understands the dependencies
between different nested tasks, usually as files that change on disk.
To see all of the tasks available, use the list
action:
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 list
:
doit info build:js:app:retro
The default doit
action is run
which... runs the named tasks.
The default tasks are lint
, build
and docs:app:build
, so the following are
equivalent:
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
changes.
By default,
auto
will invokedoit lint
which may change source files. This can be confusing to IDEs (or thewatch:docs
andwatch:js
tasks) 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:
- a
lab/index.html
and supporting assets - a
retro/*/index.html
and supporting assets (fortree
,editor
, etc.) - common configuration tools
- a
typedoc
documentation-
TBD: a set of component tarballs distributed on
npmjs.com
. See #7.
from:
- a set of
packages
in the@jupyterlite
namespace, , written in TypeScript - some
buildutils
- some
webpack
configuration - 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:
yarn bootstrap
yarn
To build development assets:
yarn build
To build production assets:
yarn build:prod
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
http
module:
yarn serve
To serve with Python's built-in
http.server
module (requires
Python 3.7+):
yarn serve:py
yarn watch
yarn lint
yarn build:test
yarn test
TBD: describe how the
@jupyterlite/labextension
works with e.g. real serverextensions
TBD: describe successor to
pyolite
, patches, etc. See #151.
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
content.
Extra 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
site.
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 app
directory),
so using the doit tools are recommended.
doit docs
Extra
sphinx-build
arguments are set by theSPHINX_ARGS
environment variable. For example to fail on all warnings (the configuration for the ReadTheDocs build):SPHINX_ARGS='["-W"]' doit docs
doit watch:docs
This also respects the
SPHINX_ARGS
variable. 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.
- Look through the existing issues (and pull requests!) to see if a related issue already exists or is being worked on
- If it is new:
- Start a new issue
- Pick an appropriate template
- Fill out the template
- Wait for the community to respond
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
main
- Make changes
- Run
doit
- Push to your fork
- Start the pull request
- your
git
CLI 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 #123
help tie the collaboration history together
- adding magic strings like
- your
- 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:
- test reports
- installable artifacts
- an app archive ready to be used as the input to the
jupyter lite
CLI with all the demo content and supporting extensions.
You must be logged in to GitHub to download these.
TBD: See #121.