updating documentation

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.
-

docs/doc-requirements.txt

@@ -0,0 +1,2 @@
+sphinx_copybutton
+alabaster_jupyterhub

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}
-

docs/source/customize.rst

@@ -0,0 +1,138 @@
+.. _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 <path-to-notebook> --template=<name-of-template>
+
+For example, Voila includes one other template that uses a Javascript library and
+an alternate ``<div>`` 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 <path-to-notebook> --template=gridstack
+
+Creating your own 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 more information, see
+`the nbconvert templates documentation <https://nbconvert.readthedocs.io/en/latest/customizing.html#Custom-Templates>`_.
+For one example, `check out the nbconvert basic HTML template <https://github.com/jupyter/nbconvert/blob/master/nbconvert/templates/html/basic.tpl>`_.
+
+Where are Voila templates located?
+----------------------------------
+
+All voila templates are stored as folders with particular configuration/template files inside.
+These folders can exist in the standard Jupyter configuration locations, in a folder called ``voila/template``.
+For example:
+
+.. code-block:: bash
+
+   ~/.local/share/jupyter/voila/template
+   ~/path/to/env/dev/share/jupyter/voila/template
+   /usr/local/share/jupyter/voila/template
+   /usr/share/jupyter/voila/template
+
+Voila will search these locations for a folder, one per template, where
+the folder name defines the template name.
+
+The Voila template structure
+----------------------------
+
+Within each template folder, you can provide your own nbconvert templates, static
+files, and HTML templates (for pages such as a 404 error). For example, here is
+the folder structure of the base Voila template (called "default"):
+
+.. code-block:: bash
+
+    tree path/to/env/share/jupyter/voila/template/default/
+    ├── nbconvert_templates
+    │   ├── base.tpl
+    │   └── voila.tpl
+    └── templates
+        ├── 404.html
+        ├── error.html
+        ├── page.html
+        └── tree.html
+
+**To customize the nbconvert template**, store it in a folder called ``templatename/nbconvert_templates/voila.tpl``.
+In the case of the default template, we also provide a ``base.tpl`` that our custom template uses as a base.
+The name ``voila.tpl`` is special - you cannot name your custom nbconvert something else.
+
+**To customize the HTML page templates**, store them i na folder called ``templatename/templates/<name>.html``.
+These are files that Voila can serve as standalone HTML (for example, the ``tree.html`` template defines how
+folders/files are displayed in ``localhost:8866/voila/tree``). You can override the defaults by providing your
+own HTML files of the same name.
+
+**To configure your Voila template**, you should add a ``config.json`` file to the root of your template
+folder.
+
+.. todo: Add information on config.json
+
+
+An example custom template
+--------------------------
+
+To show how to create your own custom template, let's create our own nbconvert template.
+We'll have two goals:
+
+1. Add an ``<h1>>`` header displaying "Our awesome template" to the voila dashboard.
+2. Add a custom 404.html page that displays an image.
+
+First, we'll create a folder in ``~/.local/share/jupyter/voila/template`` called ``mytemplate``::
+
+    mkdir ~/.local/share/jupyter/voila/template/mytemplate
+    cd ~/.local/share/jupyter/voila/template/mytemplate
+
+Next, we'll copy over the base template files for voila, which we'll modify::
+
+    cp -r path/to/env/share/jupyter/voila/template/default/nbconvert_templates ./
+    cp -r path/to/env/share/jupyter/voila/template/default/templates ./
+
+We should now have a folder structure like this::
+
+    tree .
+    ├── nbconvert_templates
+    │   ├── base.tpl
+    │   └── voila.tpl
+    └── templates
+        ├── 404.html
+        ├── error.html
+        ├── page.html
+        └── tree.html
+
+Now, we'll edit ``nbconvert_templates/voila.tpl`` to include a custom H1 header.
+
+As well as ``templates/tree.html`` to include an image.
+
+Finally, we can tell ``Voila`` to use this custom template the next time we use it on
+a Jupyter notebook by using the name of the folder in the ``--template`` parameter::
+
+voila mynotebook.ipynb --template=mytemplate
+
+The result should be a Voila dashboard with your custom modifications made!

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
+
+   <br />
+
+.. 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

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.

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 <path-to-notebook> <options>
+
+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 <https://github.com/jupyter/notebook>`_ server or with the
+   `jupyter_server <https://github.com/jupyter/jupyter_server>`_.
+
+To use Voila within a pre-existing Jupyter server, first start the server,
+then go to the following URL:
+
+.. code-block:: bash
+
+   <url-of-my-server>/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.

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

@@ -50,7 +50,7 @@ body {
                     <hr class="star-light">
                 </div>
             </div>
-    
+
             <div class="grid-stack" data-gs-width="12" data-gs-animate="yes">
                     {{ super() }}
                     <!-- <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 {
             </div>
             </div>
         </div>
-    </section>        
-    
+</section>
+
 {% endblock body %}
 
 
@@ -82,7 +82,7 @@ body {
 {% endif %}
         <div class="grid-stack-item-content">
             <div class="gridhandle">
-                <i class=" fa fa-arrows"></i> 
+                <i class=" fa fa-arrows"></i>
             </div>
         {{ super() }}
         </div>