Improved documentation

Author: JohanMabille

README.md

@@ -14,36 +14,36 @@ Launch the Jupyter notebook with `jupyter notebook` or Jupyter lab with `jupyter
 
 **Code execution and variable display**:
 
-![Basic code execution](code_exec.gif)
+![Basic code execution](docs/source/code_exec.gif)
 
 **Output streams**:
 
-![Streams](streams.gif)
+![Streams](docs/source/streams.gif)
 
 **Input streams**:
 
-![Input](input.gif)
+![Input](docs/source/input.gif)
 
 **Error handling**:
 
-![Erro handling](error.gif)
+![Erro handling](docs/source/error.gif)
 
 **Inspect**:
 
-![Inspect](inspect.gif)
+![Inspect](docs/source/inspect.gif)
 
 **Code completion**:
 
-![Completion](code_completion.gif)
+![Completion](docs/source/code_completion.gif)
 
 **Rich display**:
 
-![Rich display](rich_disp.gif)
+![Rich display](docs/source/rich_disp.gif)
 
 **And of course widgets**:
 
-![Widgets](widgets.gif)
-![Widgets binary](binary.gif)
+![Widgets](docs/source/widgets.gif)
+![Widgets binary](docs/source/binary.gif)
 
 
 ## Installation

binary.gif docs/source/binary.gif

@@ -8,11 +8,12 @@
 .. image:: xeus-python.svg
    :alt: xeus-python
 
-xeus-python is a Jupyter kernel for Python based on the C++ implementation of the Jupyter protocol xeus.
 
 Introduction
 ------------
 
+``xeus-python`` is a Jupyter kernel for Python based on the native implementation of the Jupyter protocol 
+xeus_.
 
 Licensing
 ---------
@@ -28,3 +29,11 @@ This software is licensed under the BSD-3-Clause license. See the LICENSE file f
    :maxdepth: 2
 
    installation
+
+.. toctree::
+   :caption: USAGE
+   :maxdepth: 2
+
+   usage
+
+.. _xeus: https://github.com/QuantStack/xeus

code_completion.gif docs/source/code_completion.gif

@@ -21,8 +21,25 @@
 Installation
 ============
 
-From source with cmake
-----------------------
+With Conda
+----------
+
+`xeus-python` has been packaged for the conda package manager.
+
+To ensure that the installation works, it is preferable to install `xeus-python` in a fresh conda environment.
+It is also needed to use a miniconda_ installation because with the full anaconda_ you may have a conflict with
+the `zeromq` library which is already installed in the anaconda distribution.
+
+
+The safest usage is to create an environment named `xeus-python` with your miniconda installation
+
+.. code::
+
+    conda create -n xeus-python
+    conda activate xeus-python # Or `source activate xeus-python` for conda < 4.6
+
+From Source
+-----------
 
 You can install ``xeus-python`` from source with cmake. This requires that you have all the dependencies installed in the same prefix.
 
@@ -42,3 +59,6 @@ On Windows platforms, from the source directory:
     cmake -G "NMake Makefiles" -DCMAKE_INSTALL_PREFIX=/path/to/prefix ..
     nmake
     nmake install
+
+.. _miniconda: https://conda.io/miniconda.html
+.. _anaconda: https://www.anaconda.com

code_exec.gif docs/source/code_exec.gif

@@ -0,0 +1,64 @@
+.. Copyright (c) 2017, Martin Renou, Johan Mabille, Sylvain Corlay and
+   Wolf Vollprecht
+
+   Distributed under the terms of the BSD 3-Clause License.
+
+   The full license is in the file LICENSE, distributed with this software.
+
+Usage
+=====
+
+Launch the Jupyter notebook with `jupyter notebook` or Jupyter lab with `jupyter lab` and launch
+a new Python notebook by selecting the **xpython** kernel.
+
+Code execution and variable display
+-----------------------------------
+
+.. image:: code_exec.gif
+   :alt: basic_code_execution
+
+Output streams
+--------------
+
+.. image:: streams.gif
+   :alt: streams
+
+Input streams
+-------------
+
+.. image:: input.gif
+   :alt: input
+
+Error handling
+--------------
+
+.. image:: error.gif
+   :alt: error_handling
+
+Inspect
+-------
+
+.. image:: inspect.gif
+   :alt: inspect
+
+Code completion
+---------------
+
+.. image:: code_completion.gif
+   :alt: code_completion
+
+Rich display
+------------
+
+.. image:: rich_disp.gif
+   :alt: rich_display
+
+And of course widgets
+---------------------
+
+.. image:: widgets.gif
+   :alt: widgets
+
+.. image:: binary.gif
+   :alt: widgets_binary
+