Contributing to Voilà

Voilà 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.

Community

The Voilà team organizes public video meetings. The schedule for future meetings and minutes of past meetings can be found on our team compass

Setting up a development environment

First, you need to fork the project. Then setup your environment:

# create a new conda environment
conda create -n voila -c conda-forge notebook jupyterlab nodejs "yarn<4" pip
conda activate voila

# download voila from your GitHub fork
git clone https://github.com/<your-github-username>/voila.git

# install JS dependencies and build js assets
cd voila
yarn install

# install Voilà in editable mode
python -m pip install -e .

Run Voilà

To start Voilà, run:

voila

or

python -m voila

This will open a new browser tab at [http://localhost:8866/](http://localhost:8866/).

When making changes to the frontend side of Voilà, open a new terminal window and run:

cd packages/voila/
npm run watch

Then reload the browser tab.

Note: the notebooks directory contains some examples that can be run with Voilà. Checkout the instructions in the user guide for details on how to run them.

Extensions

Server extension

To manually enable the classic notebook server extension:

jupyter serverextension enable voila --sys-prefix

For Jupyter Server:

jupyter server extension enable voila.server_extension --sys-prefix

This makes Voilà available as a server extension: http://localhost:8888/voila/tree.

Notebook extension

To install the notebook extension:

jupyter nbextension install voila --sys-prefix --py
jupyter nbextension enable voila --sys-prefix --py

JupyterLab extension

Node.js is required and can be installed with conda:

conda install -c conda-forge nodejs

The JupyterLab extension requires the server extension to be enabled. This can be done by running:

jupyter serverextension enable voila --sys-prefix

You can verify if the server extension is enabled by running:

jupyter serverextension list

If you use Jupyter Server:

jupyter server extension enable voila --sys-prefix

You can verify if the server extension is enabled by running:

jupyter server extension list

The JupyterLab extension is developed as a prebuilt extension using the new distribution system added in JupyterLab 3.0. To setup the development environment:

# install the package in development mode
python -m pip install -e .

# link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite

# build the lab extension
jlpm run build --scope @voila-dashboards/jupyterlab-preview

# it is also possible to start in watch mode to pick up changes automatically
jlpm run watch

Frontend Packages

The Voilà repository consists of several packages such as the Voilà frontend and the JupyterLab extension.

It follows a monorepo structure and uses lerna to streamline the workflow.

To build all the frontend packages at once, run the following commands:

# install dependencies
jlpm

# build the packages
jlpm run build

This will run the build script in each of the packages.

Using this structure, packages can easily be linted and follow the same code style and conventions used in other Jupyter projects. To lint the packages:

# install dependencies
jlpm

# run ESLint
jlpm run eslint

# run prettier
jlpm run prettier

About the Voila Frontend

The Voila frontend is built as a JupyterLab-based application using JupyterLab components.

This makes it possible to reuse existing plugins and extensions for Jupyterlab such as core JupyterLab plugins like the JSON viewer, as well as third-party mime renderers like the FASTA viewer.

The Voila frontend is able to load existing JupyterLab extensions installed as prebuilt extensions under ${PREFIX}/share/labextensions, similar to the way it works in JupyterLab.

These extensions are typically distributed via pip and conda packages and can easily be installed by end users without requiring Node.js. Widget packages usually now include a prebuilt extension for JupyterLab 3.0 by default, which should automatically work in Voila too.

Check out the JupyterLab Documentation on prebuilt extensions for more info.

The code for the frontend is located under packages/voila, with support for loading federated extensions in packages/voila/index.js.

Tests

Install the test dependencies

python -m pip install -e ".[test]"

Enable the Jupyter server extension:

jupyter server extension enable voila.server_extension --sys-prefix

Running the tests locally also requires the test_template and skip_template to be installed:

python -m pip install ./tests/test_template ./tests/skip_template

Finally, to run the tests:

python -m pytest

Editing templates

The default template files are located in the folder share/jupyter/voila/templates/default. They are automatically picked up when running Voilà in development mode.

After editing the templates, reload the browser tab to see the changes.