Examples with notebook, fix version

python/README.md

@@ -1,13 +1,55 @@
 # Brayns
 
-The python brayns package provides a python API to the brayns application.
+The brayns package provides a python API to the brayns application.
+
+## Documentation
+
+Brayns documentation is built and hosted on [readthedocs](https://readthedocs.org/).
+
+* [latest snapshot](http://brayns.readthedocs.org/en/latest/)
+* [latest release](http://brayns.readthedocs.org/en/stable/)
+
+## Installation
+
+It is recommended that you use [`pip`](https://pip.pypa.io/en/stable/) to install
+`Brayns` into a [`virtualenv`](https://virtualenv.pypa.io/en/stable/). The following
+assumes a `virtualenv` named `venv` has been set up and
+activated. We will see three ways to install `Brayns`
+
+
+### 1. From the Python Package Index
+
+```
+(venv)$ pip install brayns
+```
+
+### 2. From git repository
+
+```
+(venv)$ pip install git+https://github.com/BlueBrain/Brayns.git#subdirectory=python
+```
+
+### 3. From source
+
+Clone the repository and install it:
+
+```
+(venv)$ git clone https://github.com/BlueBrain/Brayns.git
+(venv)$ pip install -e ./Brayns/python
+```
+
+This installs `Brayns` into your `virtualenv` in "editable" mode. That means changes
+made to the source code are seen by the installation. To install in read-only mode, omit
+the `-e`.
+
+## Get started
 
 Simple connect:
 
 ```python
->>> import brayns
+>>> from brayns import Client
 
->>> app = brayns.Brays('localhost:8200')
->>> print(app)
+>>> brayns = brayns.Client('localhost:8200')
+>>> print(brayns)
 Brayns version 0.7.0.c52dd4b running on http://localhost:8200/
 ```

python/doc/source/conf.py

@@ -14,10 +14,9 @@
 #
 import os
 import sys
+from brayns import __version__ as VERSION
 sys.path.insert(0, os.path.abspath('../..'))
 
-exec(open('../../brayns/version.py').read())
-
 
 # -- Project information -----------------------------------------------------
 
@@ -43,7 +42,8 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    'RunNotebook.notebook_sphinxext'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -68,7 +68,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = []
+exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -165,3 +165,6 @@
 autosummary_generate = True
 autodoc_default_flags = ['show-inheritance']
 autoclass_content = 'both'
+
+run_notebook_export_template = 'basic'
+run_notebook_display_source_links = False

python/doc/source/examples.rst

@@ -0,0 +1,7 @@
+Examples
+========
+
+.. toctree::
+   :maxdepth: 3
+
+.. notebook:: ../../examples/snapshot.ipynb

python/doc/source/index.rst

@@ -15,6 +15,7 @@ It provides a generated API from the current running Brayns instance.
    :maxdepth: 3
 
    api
+   examples
 
 
 Indices and tables

python/examples/snapshot.ipynb

@@ -0,0 +1,44 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from brayns import Client\n",
+    "brayns = Client('localhost:8200')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "brayns.image(size=(400,300))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 2",
+   "language": "python",
+   "name": "python2"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

python/requirements_dev.txt

@@ -27,5 +27,6 @@ coverage~=4.5.1
 nosexcover~=1.0.11
 tox~=3.1.2
 mock~=2.0.0
-Sphinx~=1.7.6
+Sphinx~=1.6.1
 sphinx_rtd_theme~=0.4.0
+RunNotebook~=0.2.1