| Name | voici JSON |
| Version |
0.6.1
JSON |
| download |
| home_page | None |
| Summary | Voici turns Jupyter notebooks into static web applications |
| upload_time | 2024-04-23 07:57:56 |
| maintainer | None |
| docs_url | None |
| author | Voila Development Team |
| requires_python | >=3.8 |
| license | BSD License Copyright (c) 2018-2024 Voilà contributors. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: a. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. b. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. c. Neither the name of the authors nor the names of the contributors to this package may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
emscripten
jupyter
jupyterlite
voici
voila
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 
[](https://voici.readthedocs.io/en/latest/_static/lite)
[](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, 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 🏁
To use Voici, you'll need to install it first:
```bash
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:
```bash
# 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._:
```bash
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._:
```bash
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:
```bash
voici build --contents . --apps lab --apps retro
```
In order to get some help on how to use the `voici` command, you can run:
```bash
voici --help
```
We'd also suggest looking into the [JupyterLite documentation](https://jupyterlite.readthedocs.io/en/latest/howto/index.html) for more insights on how to configure your `voici` deployment.
## Build the demo site yourself
You will need either [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html), [mamba](https://mamba.readthedocs.io/en/latest) or conda installed in order to build the emscripten environment.
The [demo directory](https://github.com/voila-dashboards/voici/tree/main/demo) 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:
```bash
git clone https://github.com/voila-dashboards/voici
cd voici/demo
voici notebooks
```
Then serve it!
```bash
cd _output
python -m http.server
```
### Make your own Github pages deployment
Please follow [this guide](https://github.com/voila-dashboards/voici-demo#-how-to-make-your-own-deployment) 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](https://github.com/voila-dashboards/voici). If you'd like to contribute code, please fork the repository and submit a pull request. We welcome contributions from anyone!
Raw data
{
"_id": null,
"home_page": null,
"name": "voici",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Emscripten, Jupyter, JupyterLite, Voici, Voila",
"author": "Voila Development Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/44/89/9a38d590951c2c568152e9fc9ec700bb0711cd1c81d7aad55aee5a602166/voici-0.6.1.tar.gz",
"platform": null,
"description": "# \n\n\n[](https://voici.readthedocs.io/en/latest/_static/lite)\n[](https://voici.readthedocs.io/en/latest/?badge=latest)\n\nVoici is a tool for generating static dashboards from Jupyter Notebooks. It can be used as a drop-in replacement for [Voil\u00e0](https://github.com/voila-dashboards/voila) and it has the same commands and supports most of Voila's configuration options.\n\nUnlike 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.\n\nThis is made possible thanks to the amazing work done in the [JupyterLite project](https://github.com/jupyterlite/jupyterlite).\n\nhttps://user-images.githubusercontent.com/591645/222892327-2a5b1341-640d-49c2-9e95-1f2d3ec122be.mp4\n\n## Features \ud83d\ude80\n\n- Generates self-contained HTML files with embedded Wasm kernels.\n- Works offline, without requiring a server to run the dashboard.\n- Supports custom templates for styling dashboards, powered by Jinja2.\n- 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)\n\n## Python packages provided by voici:\n\nVoici is split between two Python packages:\n\n- The `voici-core` package provides the core functionalities of voici, mainly the voici CLI.\n- The `voici` package is a meta-package that depends on both `voici-core` and [`jupyterlite-xeus`](https://github.com/jupyterlite/xeus).\n\n`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:\n\n```yml\nname: my-dashboard-env\nchannels:\n - https://repo.mamba.pm/emscripten-forge\n - conda-forge\ndependencies:\n - xeus-python\n - matplotlib\n```\n\nIt 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.**.\n\nNote 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).\n\n```{note}\nSee the [jupyterlite-xeus documentation](https://jupyterlite-xeus.readthedocs.io/en/latest/) for more information\n```\n\nIf 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.\n\n## Getting Started \ud83c\udfc1\n\nTo use Voici, you'll need to install it first:\n\n```bash\npip install voici\n\n# OR BETTER\n\nconda install -c conda-forge voici\n\n# OR EVEN FASTER\n\nmamba install -c conda-forge voici\n```\n\nThen, you can generate static dashboards from a notebook or a directory of Notebooks like this:\n\n```bash\n# Build a single dashboard\nvoici my-notebook.ipynb\n# Build a directory of notebooks\nvoici notebooks/\n```\n\nOnce your dashboards are built, you can simply serve them with a simple static server, _e.g._:\n\n```bash\ncd _output\npython -m http.server\n```\n\n## Advanced usage\n\nThe `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.\n\nVoici runs the `build` sub-command by default, the `voici my-notebook.ipynb` command is a shortcut for `voici build --contents my-notebook.ipynb`\nFor advanced usage, users can invoke `voici` with the `jupyter lite` CLI syntax, _e.g._:\n\n```bash\nvoici build --contents my-notebook.ipynb\n```\n\nThe 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`.\n\nYou can generate the classic `jupyter lite` output alongside your dashboards by specifying the additional apps you want:\n\n```bash\nvoici build --contents . --apps lab --apps retro\n```\n\nIn order to get some help on how to use the `voici` command, you can run:\n\n```bash\nvoici --help\n```\n\nWe'd also suggest looking into the [JupyterLite documentation](https://jupyterlite.readthedocs.io/en/latest/howto/index.html) for more insights on how to configure your `voici` deployment.\n\n## Build the demo site yourself\n\nYou will need either [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html), [mamba](https://mamba.readthedocs.io/en/latest) or conda installed in order to build the emscripten environment.\n\nThe [demo directory](https://github.com/voila-dashboards/voici/tree/main/demo) contains:\n\n- `notebooks/`: The directory of Notebooks that will be served by Voici\n- `environment.yml`: The file specifying the Emscripten environment that will be used for rendering the dashboards, this must contain all your Notebook dependencies\n\nRun the following command to build the demo site:\n\n```bash\ngit clone https://github.com/voila-dashboards/voici\ncd voici/demo\n\nvoici notebooks\n```\n\nThen serve it!\n\n```bash\ncd _output\npython -m http.server\n```\n\n### Make your own Github pages deployment\n\nPlease follow [this guide](https://github.com/voila-dashboards/voici-demo#-how-to-make-your-own-deployment) for making your own Github pages deployment.\n\n## Limitations \u26a0\ufe0f\n\nBecause 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.\n\n## Contributing \ud83d\udc4b\n\nIf you find a bug or have a feature request, please open an issue on the [GitHub repository](https://github.com/voila-dashboards/voici). If you'd like to contribute code, please fork the repository and submit a pull request. We welcome contributions from anyone!\n",
"bugtrack_url": null,
"license": "BSD License Copyright (c) 2018-2024 Voil\u00e0 contributors. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: a. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. b. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. c. Neither the name of the authors nor the names of the contributors to this package may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
"summary": "Voici turns Jupyter notebooks into static web applications",
"version": "0.6.1",
"project_urls": {
"Homepage": "https://github.com/voila-dashboards/voici"
},
"split_keywords": [
"emscripten",
" jupyter",
" jupyterlite",
" voici",
" voila"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "133f33520a373da385d8390b8af21453ef5381d1d38e0ece0e1371d5ed201620",
"md5": "3e09b784f19f42455c0de550a3a24cdc",
"sha256": "d3951fa84cb0cae0519b8a49008d194dc95c839fcf3f3d4757429e67e75f7e68"
},
"downloads": -1,
"filename": "voici-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e09b784f19f42455c0de550a3a24cdc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5764,
"upload_time": "2024-04-23T07:57:53",
"upload_time_iso_8601": "2024-04-23T07:57:53.938286Z",
"url": "https://files.pythonhosted.org/packages/13/3f/33520a373da385d8390b8af21453ef5381d1d38e0ece0e1371d5ed201620/voici-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "44899a38d590951c2c568152e9fc9ec700bb0711cd1c81d7aad55aee5a602166",
"md5": "a99e039127badf3a78d3251665ec83eb",
"sha256": "3c73f6cce1c78cc4bd53ae125881fd3397ae40664f19b108905509b24441868e"
},
"downloads": -1,
"filename": "voici-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "a99e039127badf3a78d3251665ec83eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5063,
"upload_time": "2024-04-23T07:57:56",
"upload_time_iso_8601": "2024-04-23T07:57:56.071862Z",
"url": "https://files.pythonhosted.org/packages/44/89/9a38d590951c2c568152e9fc9ec700bb0711cd1c81d7aad55aee5a602166/voici-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 07:57:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "voila-dashboards",
"github_project": "voici",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "voici"
}
