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 <jeremy.tuloup@gmail.com> --------- Co-authored-by: Jeremy Tuloup <jeremy.tuloup@gmail.com>
voila-dashboards · Jan 30, 2024 · e168a9e · e168a9e
1 parent da738b6
commit e168a9e
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 15 deletions.
diff --git 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
@@ -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 🏁