Skip to content

Commit d8e5b6f

Browse files
SylvainCorlaySylvainCorlay
authored
Merge pull request #126 from choldgraf/docs
updating documentation
2 parents 6d09c40 + 82b5ec1 commit d8e5b6f

File tree

8 files changed

+282
-17
lines changed

8 files changed

+282
-17
lines changed

‎README.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Voila
22

33
[![Documentation](http://readthedocs.org/projects/voila/badge/?version=latest)](https://voila.readthedocs.io/en/latest/?badge=latest)
4-
[![Binder](https://img.shields.io/badge/launch-binder-brightgreen.svg)](https://mybinder.org/v2/gh/QuantStack/voila/stable?urlpath=voila/tree/notebooks)
4+
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/QuantStack/voila/stable?urlpath=voila%2Ftree%2Fnotebooks)
55
[![Join the Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/QuantStack/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
66

77
Rendering of live Jupyter notebooks with interactive widgets.
@@ -76,4 +76,3 @@ copyright on their contributions.
7676

7777
This software is licensed under the BSD-3-Clause license. See the
7878
[LICENSE](LICENSE) file for details.
79-

‎docs/doc-requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
sphinx_copybutton

‎docs/source/conf.py‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,12 @@
1818
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
1919

2020
html_theme = "sphinx_rtd_theme"
21-
2221
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
22+
html_theme_options = {
23+
# Toc options
24+
'sticky_navigation': False,
25+
'navigation_depth': 2,
26+
}
2327

2428
def setup(app):
2529
app.add_stylesheet("main_stylesheet.css")
@@ -49,4 +53,3 @@ def setup(app):
4953
htmlhelp_basename = 'voiladoc'
5054

5155
intersphinx_mapping = {'https://docs.python.org/': None}
52-

‎docs/source/customize.rst‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
.. _customize:
2+
3+
=================
4+
Customizing Voila
5+
=================
6+
7+
There are many ways you can customize Voila to control the look and feel
8+
of the dashboards you create.
9+
10+
Controlling the nbconvert template
11+
==================================
12+
13+
Voila uses **nbconvert** to convert your Jupyter Notebook into an HTML dashboard.
14+
nbconvert has a rich templating system that allows you to customize the way in
15+
which your Jupyter Notebook is converted into HTML.
16+
17+
By default, Voila will render the HTML from your notebook in the same linear fashion
18+
that the notebook follows. If you'd like to use a different layout, this can be
19+
controlled by creating a new nbconvert template, registering it with Voila,
20+
and calling it from the command-line like so:
21+
22+
.. code-block:: bash
23+
24+
voila <path-to-notebook> --template=<name-of-template>
25+
26+
For example, Voila includes one other template that uses a Javascript library and
27+
an alternate ``<div>`` layout in order to let the user drag and drop cells.
28+
29+
To use this template when creating your dashboard, use the following command:
30+
31+
.. code-block:: bash
32+
33+
voila <path-to-notebook> --template=gridstack
34+
35+
Creating your own template
36+
==========================
37+
38+
You can create your own nbconvert template for use with Voila. This allows you
39+
to control the look and feel of your dashboard.
40+
41+
In order to create your own template, first familiarize yourself with **Jinja**,
42+
**HTML**, and **CSS**. Each of these is used in creating custom templates.
43+
For more information, see
44+
`the nbconvert templates documentation <https://nbconvert.readthedocs.io/en/latest/customizing.html#Custom-Templates>`_.
45+
For one example, `check out the nbconvert basic HTML template <https://github.com/jupyter/nbconvert/blob/master/nbconvert/templates/html/basic.tpl>`_.
46+
47+
Where are Voila templates located?
48+
----------------------------------
49+
50+
All voila templates are stored as folders with particular configuration/template files inside.
51+
These folders can exist in the standard Jupyter configuration locations, in a folder called ``voila/template``.
52+
For example:
53+
54+
.. code-block:: bash
55+
56+
~/.local/share/jupyter/voila/template
57+
~/path/to/env/dev/share/jupyter/voila/template
58+
/usr/local/share/jupyter/voila/template
59+
/usr/share/jupyter/voila/template
60+
61+
Voila will search these locations for a folder, one per template, where
62+
the folder name defines the template name.
63+
64+
The Voila template structure
65+
----------------------------
66+
67+
Within each template folder, you can provide your own nbconvert templates, static
68+
files, and HTML templates (for pages such as a 404 error). For example, here is
69+
the folder structure of the base Voila template (called "default"):
70+
71+
.. code-block:: bash
72+
73+
tree path/to/env/share/jupyter/voila/template/default/
74+
├── nbconvert_templates
75+
│   ├── base.tpl
76+
│   └── voila.tpl
77+
└── templates
78+
├── 404.html
79+
├── error.html
80+
├── page.html
81+
└── tree.html
82+
83+
**To customize the nbconvert template**, store it in a folder called ``templatename/nbconvert_templates/voila.tpl``.
84+
In the case of the default template, we also provide a ``base.tpl`` that our custom template uses as a base.
85+
The name ``voila.tpl`` is special - you cannot name your custom nbconvert something else.
86+
87+
**To customize the HTML page templates**, store them i na folder called ``templatename/templates/<name>.html``.
88+
These are files that Voila can serve as standalone HTML (for example, the ``tree.html`` template defines how
89+
folders/files are displayed in ``localhost:8866/voila/tree``). You can override the defaults by providing your
90+
own HTML files of the same name.
91+
92+
**To configure your Voila template**, you should add a ``config.json`` file to the root of your template
93+
folder.
94+
95+
.. todo: Add information on config.json
96+
97+
98+
An example custom template
99+
--------------------------
100+
101+
To show how to create your own custom template, let's create our own nbconvert template.
102+
We'll have two goals:
103+
104+
1. Add an ``<h1>>`` header displaying "Our awesome template" to the voila dashboard.
105+
2. Add a custom 404.html page that displays an image.
106+
107+
First, we'll create a folder in ``~/.local/share/jupyter/voila/template`` called ``mytemplate``::
108+
109+
mkdir ~/.local/share/jupyter/voila/template/mytemplate
110+
cd ~/.local/share/jupyter/voila/template/mytemplate
111+
112+
Next, we'll copy over the base template files for voila, which we'll modify::
113+
114+
cp -r path/to/env/share/jupyter/voila/template/default/nbconvert_templates ./
115+
cp -r path/to/env/share/jupyter/voila/template/default/templates ./
116+
117+
We should now have a folder structure like this::
118+
119+
tree .
120+
├── nbconvert_templates
121+
│   ├── base.tpl
122+
│   └── voila.tpl
123+
└── templates
124+
├── 404.html
125+
├── error.html
126+
├── page.html
127+
└── tree.html
128+
129+
Now, we'll edit ``nbconvert_templates/voila.tpl`` to include a custom H1 header.
130+
131+
As well as ``templates/tree.html`` to include an image.
132+
133+
Finally, we can tell ``Voila`` to use this custom template the next time we use it on
134+
a Jupyter notebook by using the name of the folder in the ``--template`` parameter::
135+
136+
voila mynotebook.ipynb --template=mytemplate
137+
138+
The result should be a Voila dashboard with your custom modifications made!

‎docs/source/index.rst‎

Lines changed: 29 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,34 @@
1+
=====
12
Voila
23
=====
34

4-
Voila renders Jupyter notebooks in a read-only fashion, including live
5-
interactive widgets.
5+
Create interactive dashboards with Jupyter Notebooks.
6+
7+
Voila allows you to convert a Jupyter Notebook into an
8+
interactive dashboard that allows you to share your work with others. It
9+
is secure and customizable, giving you control over what your readers
10+
experience.
11+
12+
For example, here's a dashboard created with Voila. (you can
13+
try it interactively at the following Binder link)
14+
15+
.. image:: https://mybinder.org/badge_logo.svg
16+
:target: https://mybinder.org/v2/gh/QuantStack/voila/master?urlpath=voila%2Ftree%2Fnotebooks
17+
18+
.. raw:: html
19+
20+
<br />
21+
22+
.. image:: ../../voila-won.gif
23+
24+
Table of contents
25+
=================
26+
27+
For more information about Voila, see the sections below.
628

7-
Unlike the usual HTML-converted notebooks, each user connected to Voila gets a
8-
dedicated Jupyter kernel which can execute the callbacks to changes in Jupyter
9-
interactive widgets.
29+
.. toctree::
30+
:maxdepth: 2
1031

11-
By default, voila disallows execute requests from the front-end, disabling the
12-
ability to execute arbitrary code. By defaults, voila runs with the
13-
`strip_source` option set to `True`, which strips out the input cells from the
14-
rendered notebook.
32+
install
33+
using
34+
customize

‎docs/source/install.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
.. _install:
2+
3+
================
4+
Installing Voila
5+
================
6+
7+
Voila can be installed with the ``conda`` package manager
8+
9+
.. code-block:: bash
10+
11+
conda install -c conda-forge voila
12+
13+
or from ``PyPI``:
14+
15+
.. code-block:: bash
16+
17+
pip install voila
18+
19+
Once Voila is installed, it can be used either as a Command-Line Interface,
20+
or as a Jupyter Server extension. See :ref:`using` for information on how to use Voila.

‎docs/source/using.rst‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
.. _using:
2+
3+
===========
4+
Using Voila
5+
===========
6+
7+
Voila can be used as a standalone application, or as a Jupyter server
8+
extension. This page describes how to do each. Before you begin, make
9+
sure that you follow the steps in :ref:`install`.
10+
11+
The following sections cover how to use Voila.
12+
13+
As a standalone application
14+
===========================
15+
16+
Voila can be used to run, convert, and serve a Jupyter notebook as a
17+
standalone app. This can be done via the command-line, with the following
18+
pattern:
19+
20+
.. code-block:: bash
21+
22+
voila <path-to-notebook> <options>
23+
24+
For example, to render the ``bqplot`` example notebook as a standalone app, run
25+
26+
.. code-block:: bash
27+
28+
git clone https://github.com/QuantStack/voila
29+
cd voila
30+
voila notebooks/bqplot.ipynb
31+
32+
Voila display a message when your notebook-based application is live.
33+
By default, Voila runs at ``localhost:8866``.
34+
35+
To serve a **directory of Jupyter Notebooks**, navigate to the directory
36+
you'd like to serve, then simply run ``voila``:
37+
38+
.. code-block:: bash
39+
40+
cd notebooks/
41+
voila
42+
43+
The page served by Voila will now contain a list of any notebooks in the
44+
directory. By clicking on one, you will trigger Voila's conversion process.
45+
A new Jupyter kernel will be created for each notebook you click.
46+
47+
As a Jupyter server extension
48+
=============================
49+
50+
You can also use Voila from within a Jupyter server (e.g., after running
51+
``jupyter lab`` or ``jupyter notebook``).
52+
53+
.. note::
54+
55+
Voila can also be used as a notebook server extension, both with the
56+
`notebook <https://github.com/jupyter/notebook>`_ server or with the
57+
`jupyter_server <https://github.com/jupyter/jupyter_server>`_.
58+
59+
To use Voila within a pre-existing Jupyter server, first start the server,
60+
then go to the following URL:
61+
62+
.. code-block:: bash
63+
64+
<url-of-my-server>/voila
65+
66+
For example, if you typed ``jupyter lab`` and it was running at
67+
``http://localhost:8888/lab``, then Voila would be accessed at
68+
``http://localhost:8888/voila``.
69+
70+
In this case, Voila will serve the directory in which the Jupyter
71+
server was started.
72+
73+
How does Voila work?
74+
====================
75+
76+
When Voila is run on a notebook, the following steps occur:
77+
78+
#. Voila runs the code in the notebook and collects the outputs
79+
#. The notebook and its outputs are converted to HTML. By default,
80+
the notebook **code cells are hidden**.
81+
#. This page is served either as a Tornado application, or via the
82+
Jupyter server.
83+
#. When users access the page, the widgets on the page have access to
84+
the underlying Jupyter kernel.

‎share/jupyter/voila/template/gridstack/nbconvert_templates/voila.tpl‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ body {
5050
<hr class="star-light">
5151
</div>
5252
</div>
53-
53+
5454
<div class="grid-stack" data-gs-width="12" data-gs-animate="yes">
5555
{{ super() }}
5656
<!-- <div class="grid-stack-item" data-gs-x="0" data-gs-y="0" data-gs-width="4" data-gs-height="2">
@@ -59,8 +59,8 @@ body {
5959
</div>
6060
</div>
6161
</div>
62-
</section>
63-
62+
</section>
63+
6464
{% endblock body %}
6565

6666

@@ -82,7 +82,7 @@ body {
8282
{% endif %}
8383
<div class="grid-stack-item-content">
8484
<div class="gridhandle">
85-
<i class=" fa fa-arrows"></i>
85+
<i class=" fa fa-arrows"></i>
8686
</div>
8787
{{ super() }}
8888
</div>

0 commit comments

Comments
 (0)