From 41bb11285c4ef72c8eef3ac160f2f7b13c4007c1 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 25 Apr 2019 13:15:21 -0700 Subject: [PATCH 1/4] updating documentation --- README.md | 3 +- docs/doc-requirements.txt | 2 + docs/source/conf.py | 7 +++- docs/source/customize.rst | 64 +++++++++++++++++++++++++++++ docs/source/index.rst | 38 +++++++++++++----- docs/source/install.rst | 20 ++++++++++ docs/source/using.rst | 84 +++++++++++++++++++++++++++++++++++++++ 7 files changed, 205 insertions(+), 13 deletions(-) create mode 100755 docs/doc-requirements.txt create mode 100755 docs/source/customize.rst create mode 100755 docs/source/install.rst create mode 100755 docs/source/using.rst diff --git a/README.md b/README.md index 0f974758b..ad76fa726 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Voila [![Documentation](http://readthedocs.org/projects/voila/badge/?version=latest)](https://voila.readthedocs.io/en/latest/?badge=latest) -[![Binder](https://img.shields.io/badge/launch-binder-brightgreen.svg)](https://mybinder.org/v2/gh/QuantStack/voila/stable?urlpath=voila/tree/notebooks) +[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/QuantStack/voila/master?urlpath=voila%2Ftree%2Fnotebooks) [![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) Rendering of live Jupyter notebooks with interactive widgets. @@ -76,4 +76,3 @@ copyright on their contributions. This software is licensed under the BSD-3-Clause license. See the [LICENSE](LICENSE) file for details. - diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt new file mode 100755 index 000000000..c044b3b37 --- /dev/null +++ b/docs/doc-requirements.txt @@ -0,0 +1,2 @@ +sphinx_copybutton +alabaster_jupyterhub \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 51a2d1f5a..9d181f901 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,8 +18,12 @@ on_rtd = os.environ.get('READTHEDOCS', None) == 'True' html_theme = "sphinx_rtd_theme" - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_theme_options = { + # Toc options + 'sticky_navigation': False, + 'navigation_depth': 2, +} def setup(app): app.add_stylesheet("main_stylesheet.css") @@ -49,4 +53,3 @@ def setup(app): htmlhelp_basename = 'voiladoc' intersphinx_mapping = {'https://docs.python.org/': None} - diff --git a/docs/source/customize.rst b/docs/source/customize.rst new file mode 100755 index 000000000..98fccc3e4 --- /dev/null +++ b/docs/source/customize.rst @@ -0,0 +1,64 @@ +.. _customize: + +================= +Customizing Voila +================= + +There are many ways you can customize Voila to control the look and feel +of the dashboards you create. + +Controlling the nbconvert template +================================== + +Voila uses **nbconvert** to convert your Jupyter Notebook into an HTML dashboard. +nbconvert has a rich templating system that allows you to customize the way in +which your Jupyter Notebook is converted into HTML. + +By default, Voila will render the HTML from your notebook in the same linear fashion +that the notebook follows. If you'd like to use a different layout, this can be +controlled by creating a new nbconvert template, registering it with Voila, +and calling it from the command-line like so: + +.. code-block:: bash + + voila --template= + +For example, Voila includes one other template that uses a Javascript library and +an alternate ``
`` layout in order to let the user drag and drop cells. + +To use this template when creating your dashboard, use the following command: + +.. code-block:: bash + + voila --template=gridspec + +.. todo: double-check the command above + +Creating and registering a template +----------------------------------- + +You can create your own nbconvert template for use with Voila. This allows you +to control the look and feel of your dashboard. + +In order to create your own template, first familiarize yourself with **Jinja**, +**HTML**, and **CSS**. Each of these is used in creating custom templates. +For reference, see the TODO: link to nbconvert documentation as well as the +TODO: link to the default template for a ref. + +Once you've created your custom template, you can make register it with +Voila by + +.. todo: add information for how to register a template + + +Adding custom CSS and Javascript +================================ + +You can also add the location of any static files (CSS, JavaScript, and extra HTML) +with the ``--static`` parameter. These files will be available to be used from your template. +For example, if you have some custom CSS in a folder called ``my_css``, use the following +command to include it in rendering your dashboard: + +.. code-block:: bash + + voila --template= --static=my_css diff --git a/docs/source/index.rst b/docs/source/index.rst index fa51742a0..db065391a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,14 +1,34 @@ +===== Voila ===== -Voila renders Jupyter notebooks in a read-only fashion, including live -interactive widgets. +Create interactive dashboards with Jupyter Notebooks. + +Voila allows you to convert a Jupyter Notebook into an +interactive dashboard that allows you to share your work with others. It +is secure and customizable, giving you control over what your readers +experience. + +For example, here's a dashboard created with Voila. (you can +try it interactively at the following Binder link) + +.. image:: https://mybinder.org/badge_logo.svg + :target: https://mybinder.org/v2/gh/QuantStack/voila/master?urlpath=voila%2Ftree%2Fnotebooks + +.. raw:: html + +
+ +.. image:: ../../voila-won.gif + +Table of contents +================= + +For more information about Voila, see the sections below. -Unlike the usual HTML-converted notebooks, each user connected to Voila gets a -dedicated Jupyter kernel which can execute the callbacks to changes in Jupyter -interactive widgets. +.. toctree:: + :maxdepth: 2 -By default, voila disallows execute requests from the front-end, disabling the -ability to execute arbitrary code. By defaults, voila runs with the -`strip_source` option set to `True`, which strips out the input cells from the -rendered notebook. + install + using + customize diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100755 index 000000000..396a7c213 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,20 @@ +.. _install: + +================ +Installing Voila +================ + +Voila can be installed with the ``conda`` package manager + +.. code-block:: bash + + conda install -c conda-forge voila + +or from ``PyPI``: + +.. code-block:: bash + + pip install voila + +Once Voila is installed, it can be used either as a Command-Line Interface, +or as a Jupyter Server extension. See :ref:`using` for information on how to use Voila. diff --git a/docs/source/using.rst b/docs/source/using.rst new file mode 100755 index 000000000..d4565f9a3 --- /dev/null +++ b/docs/source/using.rst @@ -0,0 +1,84 @@ +.. _using: + +=========== +Using Voila +=========== + +Voila 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 Voila. + +As a standalone application +=========================== + +Voila 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: + +.. code-block:: bash + + voila + +For example, to render the ``bqplot`` example notebook as a standalone app, run + +.. code-block:: bash + + git clone https://github.com/QuantStack/voila + cd voila + voila notebooks/bqplot.ipynb + +Voila display a message when your notebook-based application is live. +By default, Voila runs at ``localhost:8866``. + +To serve a **directory of Jupyter Notebooks**, navigate to the directory +you'd like to serve, then simply run ``voila``: + +.. code-block:: bash + + cd notebooks/ + voila + +The page served by Voila will now contain a list of any notebooks in the +directory. By clicking on one, you will trigger Voila's conversion process. +A new Jupyter kernel will be created for each notebook you click. + +As a Jupyter server extension +============================= + +You can also use Voila from within a Jupyter server (e.g., after running +``jupyter lab`` or ``jupyter notebook``). + +.. note:: + + Voila can also be used as a notebook server extension, both with the + `notebook `_ server or with the + `jupyter_server `_. + +To use Voila within a pre-existing Jupyter server, first start the server, +then go to the following URL: + +.. code-block:: bash + + /voila + +For example, if you typed ``jupyter lab`` and it was running at +``http://localhost:8888/lab``, then Voila would be accessed at +``http://localhost:8888/voila``. + +In this case, Voila will serve the directory in which the Jupyter +server was started. + +How does Voila work? +==================== + +When Voila is run on a notebook, the following steps occur: + +#. Voila 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. \ No newline at end of file From e622fd92aac847e29268a8327c4c74a84322de4d Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 29 Apr 2019 16:06:23 -0700 Subject: [PATCH 2/4] small doc edits --- docs/source/customize.rst | 9 ++++----- .../template/gridstack/nbconvert_templates/voila.tpl | 8 ++++---- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/source/customize.rst b/docs/source/customize.rst index 98fccc3e4..4e0ef2283 100755 --- a/docs/source/customize.rst +++ b/docs/source/customize.rst @@ -30,9 +30,7 @@ To use this template when creating your dashboard, use the following command: .. code-block:: bash - voila --template=gridspec - -.. todo: double-check the command above + voila --template=gridstack Creating and registering a template ----------------------------------- @@ -42,8 +40,9 @@ to control the look and feel of your dashboard. In order to create your own template, first familiarize yourself with **Jinja**, **HTML**, and **CSS**. Each of these is used in creating custom templates. -For reference, see the TODO: link to nbconvert documentation as well as the -TODO: link to the default template for a ref. +For more information, see +`the nbconvert templates documentation `_. +For one example, `check out the nbconvert basic HTML template `_. Once you've created your custom template, you can make register it with Voila by diff --git a/share/jupyter/voila/template/gridstack/nbconvert_templates/voila.tpl b/share/jupyter/voila/template/gridstack/nbconvert_templates/voila.tpl index 861aebf87..986b27071 100644 --- a/share/jupyter/voila/template/gridstack/nbconvert_templates/voila.tpl +++ b/share/jupyter/voila/template/gridstack/nbconvert_templates/voila.tpl @@ -50,7 +50,7 @@ body {
- +
{{ super() }}