Skip to main content

Voici turns Jupyter notebooks into static web applications

Project description

voici

Github Actions Status JupyterLite Documentation Status

Voici is a tool for generating static dashboards from Jupyter Notebooks. It can be used as a drop-in replacement for Voilà and it has the same commands and supports most of Voila's configuration options.

Unlike Voila, which renders interactive dashboards using server-side execution, Voici uses WebAssembly (Wasm) kernels to render notebooks in the browser, making the resulting dashboard entirely self-contained and distributable.

This is made possible thanks to the amazing work done in the JupyterLite project.

https://user-images.githubusercontent.com/591645/222892327-2a5b1341-640d-49c2-9e95-1f2d3ec122be.mp4

Features 🚀

  • Generates self-contained HTML files with embedded Wasm kernels.
  • Works offline, without requiring a server to run the dashboard.
  • Supports custom templates for styling dashboards, powered by Jinja2.
  • Supports all programming languages that have JupyterLite kernels available. e.g. the default JavaScript and Python kernels JupyterLite provides, and xeus kernels

Python packages provided by voici:

Voici is split between two Python packages:

  • The voici-core package provides the core functionalities of voici, mainly the voici CLI.
  • The voici package is a meta-package that depends on both voici-core and jupyterlite-xeus.

jupyterlite-xeus allows you to pre-install packages for running your dashboard. For example, if your dashboard requires Matplotlib you can provide an environment.yml file in the folder where you run the voici command, containing the following:

name: my-dashboard-env
channels:
  - https://repo.mamba.pm/emscripten-forge
  - conda-forge
dependencies:
  - xeus-python
  - matplotlib

It has been decided that voici would depend on jupyterlite-xeus for convenience, allowing to easily switch from voila to voici without the need to update the Notebook code..

Note that you can install multiple xeus kernels like xeus-python, xeus-lua or xeus-javascript.

See the [jupyterlite-xeus documentation](https://jupyterlite-xeus.readthedocs.io/en/latest/) for more information

If you would like to use https://github.com/jupyterlite/pyodide-kernel or another non-xeus kernel, you may want to depend on voici-core and jupyterlite-pyodide-kernel instead.

Getting Started 🏁

To use Voici, you'll need to install it first:

pip install voici

# OR BETTER

conda install -c conda-forge voici

# OR EVEN FASTER

mamba install -c conda-forge voici

Then, you can generate static dashboards from a notebook or a directory of Notebooks like this:

# Build a single dashboard
voici my-notebook.ipynb
# Build a directory of notebooks
voici notebooks/

Once your dashboards are built, you can simply serve them with a simple static server, e.g.:

cd _output
python -m http.server

Advanced usage

The voici command line interface is a mix between voila and jupyter lite. For most cases, users can rely on the voici command by using the voila CLI syntax.

Voici runs the build sub-command by default, the voici my-notebook.ipynb command is a shortcut for voici build --contents my-notebook.ipynb For advanced usage, users can invoke voici with the jupyter lite CLI syntax, e.g.:

voici build --contents my-notebook.ipynb

The difference between voici build and jupyter lite build commands is that the voici one will only generate Voici dashboards, excluding the full JupyterLab interface from the output. Running voici build --contents . is equivalent to running jupyter lite build --contents . --apps voici.

You can generate the classic jupyter lite output alongside your dashboards by specifying the additional apps you want:

voici build --contents . --apps lab --apps retro

In order to get some help on how to use the voici command, you can run:

voici --help

We'd also suggest looking into the JupyterLite documentation for more insights on how to configure your voici deployment.

Build the demo site yourself

You will need either micromamba, mamba or conda installed in order to build the emscripten environment.

The demo directory contains:

  • notebooks/: The directory of Notebooks that will be served by Voici
  • environment.yml: The file specifying the Emscripten environment that will be used for rendering the dashboards, this must contain all your Notebook dependencies

Run the following command to build the demo site:

git clone https://github.com/voila-dashboards/voici
cd voici/demo

voici notebooks

Then serve it!

cd _output
python -m http.server

Make your own Github pages deployment

Please follow this guide for making your own Github pages deployment.

Limitations ⚠️

Because Voici uses Wasm kernels to execute notebooks, there are some limitations to the types of notebooks that can be rendered: Some notebook features may not work correctly or may have limited functionality when rendered in Voici.

Contributing 👋

If you find a bug or have a feature request, please open an issue on the GitHub repository. If you'd like to contribute code, please fork the repository and submit a pull request. We welcome contributions from anyone!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

voici-0.6.1.tar.gz (5.1 kB view details)

Uploaded Source

Built Distribution

voici-0.6.1-py3-none-any.whl (5.8 kB view details)

Uploaded Python 3

File details

Details for the file voici-0.6.1.tar.gz.

File metadata

  • Download URL: voici-0.6.1.tar.gz
  • Upload date:
  • Size: 5.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.11.9

File hashes

Hashes for voici-0.6.1.tar.gz
Algorithm Hash digest
SHA256 3c73f6cce1c78cc4bd53ae125881fd3397ae40664f19b108905509b24441868e
MD5 a99e039127badf3a78d3251665ec83eb
BLAKE2b-256 44899a38d590951c2c568152e9fc9ec700bb0711cd1c81d7aad55aee5a602166

See more details on using hashes here.

Provenance

File details

Details for the file voici-0.6.1-py3-none-any.whl.

File metadata

  • Download URL: voici-0.6.1-py3-none-any.whl
  • Upload date:
  • Size: 5.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.11.9

File hashes

Hashes for voici-0.6.1-py3-none-any.whl
Algorithm Hash digest
SHA256 d3951fa84cb0cae0519b8a49008d194dc95c839fcf3f3d4757429e67e75f7e68
MD5 3e09b784f19f42455c0de550a3a24cdc
BLAKE2b-256 133f33520a373da385d8390b8af21453ef5381d1d38e0ece0e1371d5ed201620

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page