Merge pull request #441 from SylvainCorlay/update-contributing-guidel…

…ines

Update contributing guidelines

CONTRIBUTING.md

@@ -1,9 +1,15 @@
-# Contributing to voila
+# Contributing to Voilà
+
+Voilà is a subproject of Project Jupyter and subject to the [Jupyter governance](https://github.com/jupyter/governance) and [Code of conduct](https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md).
 
 ## General Guidelines
 
 For general documentation about contributing to Jupyter projects, see the [Project Jupyter Contributor Documentation](https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html).
 
+## Community
+
+The Voilà team organizes public video meetings. The schedule for future meetings and minutes of past meetings can be found on our [team compass](https://voila-dashboards.github.io/).
+
 ## Setting up a development environment
 
 First, you need to fork the project. Then setup your environment:
@@ -25,9 +31,9 @@ cd ..
 python -m pip install -e .
 ```
 
-## Run voila
+## Run Voilà
 
-To start voila, run:
+To start Voilà, run:
 
 ```bash
 voila
@@ -41,7 +47,7 @@ python -m voila
 
 This will open a new browser tab at [http://localhost:8866/](http://localhost:8866/).
 
-When making changes to the frontend side of voila, open a new terminal window and run:
+When making changes to the frontend side of Voilà, open a new terminal window and run:
 
 ```bash
 cd js/
@@ -66,7 +72,7 @@ For Jupyter Server:
 jupyter extension enable voila --sys-prefix
 ```
 
-This makes voila available as a server extension: [http://localhost:8888/voila/tree](http://localhost:8888/voila/tree).
+This makes Voilà available as a server extension: [http://localhost:8888/voila/tree](http://localhost:8888/voila/tree).
 
 ### Notebook extension
 
@@ -148,9 +154,8 @@ Finally, to run the tests:
 python -m pytest
 ```
 
-
 ## Editing templates
 
-The default templates are located in the following folder: [share/jupyter/voila/templates/default](./share/jupyter/voila/templates/default). They are automatically picked up when running voila in development mode.
+The default template files are located in the folder `share/jupyter/voila/templates/default`. They are automatically picked up when running Voilà in development mode.
 
 After editing the templates, reload the browser tab to see the changes.

README.md

@@ -1,7 +1,7 @@
 # ![voila](docs/source/voila-logo.svg)
 
 [![Documentation](http://readthedocs.org/projects/voila/badge/?version=latest)](https://voila.readthedocs.io/en/latest/?badge=latest)
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/QuantStack/voila/stable?urlpath=voila%2Ftree%2Fnotebooks)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/voila-gridstack/voila/stable?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.
@@ -14,9 +14,9 @@ Unlike the usual HTML-converted notebooks, each user connecting to the Voilà
 tornado application gets a dedicated Jupyter kernel which can execute the
 callbacks to changes in Jupyter interactive widgets.
 
-- By default, voila disallows execute requests from the front-end, preventing
+- By default, Voilà disallows execute requests from the front-end, preventing
   execution of arbitrary code.
-- By default, voila runs with the `strip_source` option, which strips out the
+- By default, Voilà runs with the `strip_source` option, which strips out the
   input cells from the rendered notebook.
 
 ## Installation
@@ -49,7 +49,7 @@ To render the `bqplot` example notebook as a standalone app, run
 `voila bqplot.ipynb`.
 To serve a directory of jupyter notebooks, run `voila` with no argument.
 
-For example, to render the example notebook `bqplot.ipynb` from this repository with voila, you can first update your current environment with the requirements of this notebook (in this case in a [conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) and render the notebook with
+For example, to render the example notebook `bqplot.ipynb` from this repository with Voilà, you can first update your current environment with the requirements of this notebook (in this case in a [conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) and render the notebook with
 
 ```
 conda env update -f environment.yml
@@ -72,7 +72,7 @@ To install the notebook server extension, run
 jupyter serverextension enable voila --sys-prefix
 ```
 
-When running the notebook server, the voila app is accessible from the base url
+When running the notebook server, the Voilà app is accessible from the base url
 suffixed with `voila`.
 
 ## Documentation
@@ -86,23 +86,23 @@ https://voila.readthedocs.io/
 The following two examples show how a standalone Jupyter notebook can be turned into a separate app, from the command-line integration.
 
 **Rendering a notebook including interactive widgets and rich mime-type rendering**
-![voila basics](voila-basics.gif)
+![Voila basics](voila-basics.gif)
 
 **Rendering a notebook making use of a custom widget library ([bqplot](https://github.com/bloomberg/bqplot))**
 
-![voila bqplot](voila-bqplot.gif)
+![Voila bqplot](voila-bqplot.gif)
 
-**Showing the source code for a voila notebook**
+**Showing the source code for a Voilà notebook**
 
-The sources of the Jupyter notebook can be displayed in a voila app if option `strip_sources` is set to `False`.
+The sources of the Jupyter notebook can be displayed in a Voilà app if option `strip_sources` is set to `False`.
 
-![voila sources](voila-sources.gif)
+![Voila sources](voila-sources.gif)
 
 **Voilà dashboards with other language kernels**
 
-Voilà is built upon Jupyter standard formats and protocols, and is agnostic to the programming language of the notebook. In this example, we present an example of a voila application powered by the C++ Jupyter kernel [xeus-cling](https://github.com/QuantStack/xeus-cling), and the [xleaflet](https://github.com/QuantStack/xleaflet) project.
+Voilà is built upon Jupyter standard formats and protocols, and is agnostic to the programming language of the notebook. In this example, we present an example of a Voilà application powered by the C++ Jupyter kernel [xeus-cling](https://github.com/QuantStack/xeus-cling), and the [xleaflet](https://github.com/QuantStack/xleaflet) project.
 
-![voila cling](voila-cling.gif)
+![Voila cling](voila-cling.gif)
 
 ## The Voilà Gallery
 

RELEASE.md

@@ -1,4 +1,4 @@
-# Making a new release of voila
+# Making a new release of Voilà
 
 ## Getting a clean environment
 

docs/source/contribute.rst

@@ -0,0 +1,184 @@
+.. Copyright (c) 2018, Voila 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.
+
+.. _install:
+
+=====================
+Contributing to Voilà
+=====================
+
+Voilà is a subproject of Project Jupyter and subject to the `Jupyter governance <https://github.com/jupyter/governance>`_ and `Code of conduct <https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md>`_.
+
+General Guidelines
+==================
+
+For general documentation about contributing to Jupyter projects, see the `Project Jupyter Contributor Documentation <https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html>`_.
+
+Community
+=========
+
+The Voilà team organizes public video meetings. The schedule for future meetings and minutes of past meetings can be found on our `team compass <https://voila-dashboards.github.io/>`_
+
+Setting up a development environment
+====================================
+
+First, you need to fork the project. Then setup your environment:
+
+.. code-block:: bash
+
+   # create a new conda environment
+   conda create -n voila -c conda-forge notebook nodejs
+   conda activate voila
+
+   # download voila from your GitHub fork
+   git clone https://github.com/<your-github-username>/voila.git
+
+   # install JS dependencies and build js assets
+   cd voila/js
+   npm install
+   cd ..
+
+   # install Voila in editable mode
+   python -m pip install -e .
+
+Run Voilà
+=========
+
+To start Voilà, run:
+
+.. code-block:: bash
+
+   voila
+
+or
+
+.. code-block:: bash
+
+   python -m voila
+
+This will open a new browser tab at [http://localhost:8866/](http://localhost:8866/).
+
+When making changes to the frontend side of Voilà, open a new terminal window and run:
+
+.. code-block:: bash
+
+   cd js/
+   npm run watch
+
+Then reload the browser tab.
+
+Extensions
+==========
+
+Server extension
+----------------
+
+To manually enable the classic notebook server extension:
+
+.. code-block:: bash
+
+   jupyter serverextension enable voila --sys-prefix
+
+For Jupyter Server:
+
+.. code-block:: bash
+
+   jupyter extension enable voila --sys-prefix
+
+This makes Voilà available as a server extension: `http://localhost:8888/voila/tree <http://localhost:8888/voila/tree>`_.
+
+Notebook extension
+------------------
+
+To install the notebook extension:
+
+.. code-block:: bash
+
+   jupyter nbextension install voila --sys-prefix --py
+   jupyter nbextension enable voila --sys-prefix --py
+
+JupyterLab extension
+--------------------
+
+Node.js is required and can be installed with conda:
+
+.. code-block:: bash
+
+   conda install -c conda-forge nodejs
+
+The JupyterLab extension requires the server extension to be enabled. This can be done by running:
+
+.. code-block:: bash
+
+   jupyter serverextension enable voila --sys-prefix
+
+You can verify if the server extension is enabled by running:
+
+.. code-block:: bash
+
+   jupyter serverextension list
+
+To install the JupyterLab extension locally:
+
+.. code-block:: bash
+
+   jupyter labextension install @jupyter-widgets/jupyterlab-manager
+   jupyter labextension install ./packages/jupyterlab-voila
+   
+   # start in watch mode to pick up changes automatically
+   jupyter lab --watch
+
+Running the examples
+====================
+
+A few additional libraries can be installed to run the example notebooks:
+
+.. code-block:: bash
+
+   conda install -c conda-forge ipywidgets ipyvolume bqplot scipy
+
+The examples can then be served with:
+
+.. code-block:: bash
+
+   cd notebooks/
+   voila
+
+Tests
+=====
+
+Install the test dependencies
+
+.. code-block:: bash
+
+   python -m pip install -e ".[test]"
+
+Enable the Jupyter server extension:
+
+.. code-block:: bash
+
+   jupyter extension enable voila --sys-prefix
+
+Running the tests locally also requires the `test_template` to be installed:
+
+.. code-block:: bash
+
+   python -m pip install ./tests/test_template
+
+Finally, to run the tests:
+
+.. code-block:: bash
+
+   python -m pytest
+
+Editing templates
+=================
+
+The default template files are located in the folder `share/jupyter/voila/templates/default`. They are automatically picked up when running Voilà in development mode.
+
+After editing the templates, reload the browser tab to see the changes.
+