Skip to content

Latest commit

 

History

History
124 lines (84 loc) · 2.8 KB

CONTRIBUTING.md

File metadata and controls

124 lines (84 loc) · 2.8 KB
Raw

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 in postBuild 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 DockBox
  • be 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