CONTRIBUTING.md

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 nodejs
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/js
npm install
cd ..

# 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/.

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

cd js/
npm run watch

Then reload the browser tab.

Extensions

Server extension

To manually enable the classic notebook server extension:

jupyter serverextension enable voila --sys-prefix

For Jupyter Server:

jupyter extension enable voila --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

To install the JupyterLab extension locally:

cd ./packages/jupyterlab-voila

jlpm
jlpm run build
jupyter labextension install @jupyter-widgets/jupyterlab-manager . --debug

# start in watch mode to pick up changes automatically
jupyter lab --watch

Running the examples

A few additional libraries can be installed to run the example notebooks:

conda install -c conda-forge ipywidgets ipyvolume bqplot scipy

The examples can then be served with:

cd notebooks/
voila

Tests

Install the test dependencies

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

Enable the Jupyter server extension:

jupyter extension enable voila --sys-prefix

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

python -m pip install ./tests/test_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.

Alternatively, there is a Voilà template cookiecutter available to give you a running start. Link. This cookiecutter contains some docker configuration for live reloading of your template changes to make development easier.