Contributing to Lumino

Lumino is a subproject of Project Jupyter and subject to the Jupyter governance and Code of conduct.

General Guidelines

For general documentation about contributing to Jupyter projects, see the Project Jupyter Contributor Documentation.

Setting up a development environment

Lumino requires nodejs and yarn for local development. After cloning Lumino, run the following to install dependencies and build the source:

yarn
yarn build:src

Tests

The tests are written using web-test-runner to test in browser environment (provided by playwright).

If you have never installed playwright before or updated it, you need to install the browsers by executing:

yarn playwright install

To run the tests, run:

yarn build:test
yarn test  # optionally test:chromium, test:firefox, or test:webkit

You can run the tests manually to debug them by going inside one package (e.g. packages/application) and then executing yarn test:debug. This should open your browser in which you will be able to select the test file to execute. The outcome of the tests are displayed in the web browser console and you can use the web browser debug capability to debug the tests.

Note

The test files are transpiled and bundled before execution. Therefore when debugging in the browser, you must use the file tests/lib/bundle.test.js. Then you will need to apply the fix to the Typescript test file and re-run the test command (to trigger the bundling) to check the test is fixed.

Examples

Lumino examples are in the examples/ folder. To build and run an example:

yarn build:src
yarn minimize
yarn build:examples
cd example/dockpanel

Open the index.html file in a browser to see the running example.

There are also tests in some of the examples. These can be run as:

yarn test:examples

Static Examples

There are static examples built into the documentation. Having them in docs allows us to test examples in the ReadTheDocs build for a PR.

To add an example to the static examples:

Add appropriate link in: docs/source/examples.rst
Add the example name to the EXAMPLES in docs/source/conf.py
Add ignore-links config in package.json

Documentation

The documentation is built with sphinx making use of the PyData Sphinx theme.

To build it locally

create and activate an isolated development environment with the necessary dependencies with

conda env create -f docs/environment.yml
conda activate lumino_documentation

build, for example the html version, with

cd docs
make html

The HTML pages are then located in the build/html directory.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!