Contributing#
Get Mambaforge. Start a dev environment from a lockfile, list tasks, launch Lab:
mamba create --prefix envs/docs --file .github/locks/conda.docs.linux-64-3.11-3.5.lock
source activate envs/docs
doit list --status --all
doit lab
Use doit#
Local development and continuous integration are both driven by pydoit.
View all doit commands#
doit list
--all
and--status
can be combined for a lot of quick information.
doit list --all --status | sort
Run everything up to development#
doit
This actually runs the
binder
task, which is used inpostBuild
for the interactive demo
The equivalent of starting Binder is:
doit lab
Do everything to prepare for a release#
doit release
Do everything to prepare the docs site#
doit release
doit docs
This is two un-coupled
doit
runs, so that it possible to replace notebook widget data or screenshots “hot” without worry too much about where they came from.
Live Development#
To rebuild the labextension and your JupyterLab, use:
doit watch:lab
When new files are created, it is usually necessary to re-start the watch command, stop it with Ctrl+C.
Semi-incompatibly, you can live run the docs build process (with some limitations)
doit watch:docs
Testing#
Notebooks#
Tests are primarily captured as executable notebooks imported (or linked) to from the notebook index.
Each notebook should:
have a descriptive name
demonstrate the value provided by the widgets in question as simply as possible
provide a higher-level confection of
wxyz
widgets, usually a DockBoxbe imported into the index, unless it has very taxing, less-portable dependencies
Robot Framework Testing#
Where appropriate, individual components should be tested with Robot Framework tests. Ideal tests include thoroughly exercising the demo notebooks as a user would.
doit robot
Code Style#
Code style is enforced by a number of python, typescript and miscellaneous files (e.g. YAML, JSON).
doit lint
Updating lockfiles#
The lockfiles in .github/locks
are created in a separate environment from the main
development environment to avoid a conda
dependency. mamba
is recommended, as many
solutions are run.
mamba create --prefix envs/lock --file .github/locks/conda.lock.linux-64-3.11-.lock
source envs/lock/bin/activate
doit list --all --status
CONDA_EXE=mamba CONDARC=.github/.condarc doit -n4 lock