% Copyright (c) 2018, Voilà Contributors % Copyright (c) 2018, QuantStack % % Distributed under the terms of the BSD 3-Clause License. % % The full license is in the file LICENSE, distributed with this software.
(using)=
Voilà can be used as a standalone application, or as a Jupyter server
extension. This page describes how to do each. Before you begin, make
sure that you follow the steps in {ref}install
.
The following sections cover how to use Voilà.
Voilà can be used to run, convert, and serve a Jupyter notebook as a standalone app. This can be done via the command-line, with the following pattern:
voila <path-to-notebook> <options>
For example, to render the bqplot
example notebook as a standalone app, run
git clone https://github.com/voila-dashboards/voila
cd voila
voila notebooks/bqplot.ipynb
Voilà displays a message when your notebook-based application is live.
By default, Voilà runs at localhost:8866
.
To serve a directory of Jupyter Notebooks, navigate to the directory
you'd like to serve, then simply run voila
:
cd notebooks/
voila
The page served by Voilà will now contain a list of any notebooks in the directory. By clicking on one, you will trigger Voilà's conversion process. A new Jupyter kernel will be created for each notebook you click.
You can also use Voilà from within a Jupyter server (e.g., after running
jupyter lab
or jupyter notebook
).
:::{note} Voilà can also be used as a notebook server extension, both with the notebook server or with the jupyter_server. :::
To use Voilà within a pre-existing Jupyter server, first start the server, then go to the following URL:
<url-of-my-server>/voila
For example, if you typed jupyter lab
and it was running at
http://localhost:8888/lab
, then Voilà would be accessed at
http://localhost:8888/voila
.
In this case, Voilà will serve the directory in which the Jupyter server was started.
When Voilà is run on a notebook, the following steps occur:
- Voilà runs the code in the notebook and collects the outputs
- The notebook and its outputs are converted to HTML. By default, the notebook code cells are hidden.
- This page is served either as a Tornado application, or via the Jupyter server.
- When users access the page, the widgets on the page have access to the underlying Jupyter kernel.
The notebooks directory contains a collection of Jupyter notebooks that can be rendered using Voilà:
- basics.ipynb - a notebook with interactions requiring a roundtrip to the kernel.
- bqplot.ipynb - uses custom Jupyter widgets such as bqplot.
- dashboard.ipynb - uses gridstack.js for the layout of each output.
- gridspecLayout.ipynb - uses GridspecLayout for the layout of different widgets.
- interactive.ipynb - makes use of ipywidget's @interact.
- ipympl.ipynb - contains custom interactive matplotlib figures using the ipympl widget.
- ipyvolume.ipynb - uses custom Jupyter widgets such as ipyvolume.
- query-strings.ipynb - uses HTTP query parameters to parametrize a notebook
- xleaflet.ipynb - a notebook that uses C++ kernel and interactive widgets
These examples demonstrate different interactive HTML widgets and can be used as inspiration for getting started with Voilà.
To run the example notebooks, a few additional libraries can be installed using:
conda install -c conda-forge ipywidgets ipyvolume bqplot scipy
Or alternatively:
conda env create
The examples can then be served with:
cd notebooks/
voila