contribute.rst

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 Voila 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 js/
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 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:

jupyter labextension install @jupyter-widgets/jupyterlab-manager
jupyter labextension install ./packages/jupyterlab-voila

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

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.

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