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.