From e168a9ee9e6be15a45726e248dc2e38fc007f483 Mon Sep 17 00:00:00 2001 From: martinRenou Date: Tue, 30 Jan 2024 14:39:36 +0100 Subject: [PATCH] README: clarify voici and voici-core differences (#110) * README: clarify voici and voici-core differences * Add more information * Jeremy suggestions Co-authored-by: Jeremy Tuloup --------- Co-authored-by: Jeremy Tuloup --- python/voici-core/README.md | 15 +-------------- python/voici/README.md | 31 ++++++++++++++++++++++++++++++- 2 files changed, 31 insertions(+), 15 deletions(-) diff --git a/python/voici-core/README.md b/python/voici-core/README.md index 4e4bef9..9e9ff23 100644 --- a/python/voici-core/README.md +++ b/python/voici-core/README.md @@ -4,20 +4,7 @@ [![JupyterLite](https://jupyterlite.rtfd.io/en/latest/_static/badge-launch.svg)](https://voici.readthedocs.io/en/latest/_static/lite) [![Documentation Status](https://readthedocs.org/projects/voici/badge/?version=latest)](https://voici.readthedocs.io/en/latest/?badge=latest) -Voici is a tool for generating static dashboards from Jupyter Notebooks. It can be used as a drop-in replacement for [Voilà](https://github.com/voila-dashboards/voila) 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](https://developer.mozilla.org/en-US/docs/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://github.com/jupyterlite/jupyterlite). - -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, [python, lua or nelson with xeus](https://github.com/jupyterlite/xeus) +The `voici-core` package provides the core functionality for building voici dashboards using the voici CLI. ## Getting Started 🏁 diff --git a/python/voici/README.md b/python/voici/README.md index ea19bf5..ec33a04 100644 --- a/python/voici/README.md +++ b/python/voici/README.md @@ -17,7 +17,36 @@ https://user-images.githubusercontent.com/591645/222892327-2a5b1341-640d-49c2-9e - 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, [python with xeus-python](https://github.com/jupyterlite/xeus-python-kernel), [lua](https://github.com/jupyterlite/xeus-lua-kernel), [nelson](https://github.com/jupyterlite/xeus-nelson-kernel) +- Supports all programming languages that have JupyterLite kernels available. _e.g._ the default JavaScript and Python kernels JupyterLite provides, and [xeus kernels](https://github.com/jupyterlite/xeus) + +## 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`](https://github.com/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: + +```yml +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](https://github.com/jupyter-xeus/xeus-python), [xeus-lua](https://github.com/jupyter-xeus/xeus-lua) or [xeus-javascript](https://github.com/jupyter-xeus/xeus-javascript). + +```{note} +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 🏁