diff --git a/HOWTO_UPLOAD_TO_PYPI b/HOWTO_UPLOAD_TO_PYPI
new file mode 100644
index 0000000000000000000000000000000000000000..37168d54395d7c71a62b9b7dcfa6e8186bd14d43
--- /dev/null
+++ b/HOWTO_UPLOAD_TO_PYPI
@@ -0,0 +1,12 @@
+# Convert README.md markdown to README.rst reStructuredText
+pandoc --from=markdown --to=rst --output=README.rst README.md
+
+# create a source-distribution
+python setup.py sdist
+
+# see distributions
+ls -la dist/
+
+# upload distribution(s) to pypi
+twine upload dist/*
+
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7fa2e19ef7be4038a1f716b8f111a7e731191ecb
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,162 @@
+Jupyter-OpenBIS-Extension
+=========================
+
+Requirements
+------------
+
+The jupyter-openbis-extension needs at least **Python 3.3** in order to
+run. The Jupyter notebook server starts this extension during startup
+and must therefore run under the same Python version. The kernel can be
+anything (Python 2.7, Julia, R, Perl...)
+
+This extension has been successfully tested with Safari 12.0.3, Chrome
+72.0 and Firefox 66.0. There is a known incompatibility before Firefox
+61.0b13.
+
+Install the extension
+---------------------
+
+If you haven't done yet: download the latest jupyter-openbis-extension
+from pip. It will automatically install the various dependencies, e.g.
+Pandas and NumPy.
+
+::
+
+ pip install --upgrade jupyter-openbis-extension
+
+Create a configuration file
+---------------------------
+
+This step is not really necessary, as you can define openBIS connections
+within the Jupyter notebook. However, if you need to connect to the same
+openBIS connections many times, this will become convenient. Create a
+file ``openbis-connections.yaml``. It should contain connection
+information to your server(s), for example:
+
+::
+
+ connections:
+ - name : TEST local openBIS instance
+ url : https://localhost:8443
+ verify_certificates : false
+ username : username
+ password : password
+ - name : PRODUCTION openBIS instance
+ url : https://openbis.example.com
+ verify_certificates : true
+ username : username
+
+**Note 1**: You do not need neither username nor password. With the
+current version, you are able to enter username and password directly
+from within a Jupyter notebook.
+
+**Note 2**: Place this file in any of these directories (on Mac OS X):
+
+::
+
+ /Users/your_username/jupyter-openbis-extension/notebooks
+ /Users/your_username/.jupyter
+ /Users/your_username/.pyenv/versions/3.6.0/etc/jupyter # or wherever your jupyter installation is located
+ /usr/local/etc/jupyter
+ /etc/jupyter
+
+These directories can be found by invoking
+
+::
+
+ $ jupyter --paths
+
+The ``config`` section from the output lists the directories where your
+``openbis-connections.yaml`` file should be placed.
+
+Launching Jupyter notebook
+--------------------------
+
+Now you are ready to launch Jupyter notebook:
+
+::
+
+ $ jupyter notebook --no-browser
+
+Observe the terminal. It should tell you which server(s) have been
+registered. If you provided a password, it will try to connect:
+
+::
+
+ $ jupyter notebook
+ Registered: https://localhost:8443
+ Successfully connected to: https://localhost:8443
+ Registered: https://openbis.example.com
+
+**Congratulations!** You can retry non-successful connections later,
+directly from the GUI. Copy the the URL given in the output and paste it
+in your browser. You might also just start Jupyter without the
+``--no-browser`` option.
+
+Uninstall Jupyter extension
+---------------------------
+
+::
+
+ $ jupyter serverextension disable --py jupyter-openbis-extension
+ $ jupyter nbextension disable --py jupyter-openbis-extension --user
+ $ jupyter nbextension uninstall --py jupyter-openbis-extension --user
+
+This should remove the registrations in the paths listed by the
+
+::
+
+ $ jupyter --paths
+
+command.
+
+Development with Vagrant
+------------------------
+
+If you want to use a predefined development environment, follow these
+steps:
+
+1. Install latest version of VirtualBox (https://www.virtualbox.org)
+
+2. Install latest version of Vagrant
+ (https://www.vagrantup.com/downloads.html)
+
+3. vagrant plugin install vagrant-vbguest vagrant-notify-forwarder
+ vagrant-disksize
+
+4. cd vagrant
+
+5. vagrant up
+
+After the setup is complete, you'll have
+
+- Jupyter with openBIS extension running at http://localhost:8888.
+- openBIS running at http://localhost:8122, with credentials
+ admin/password.
+- Experiment /DEFAULT/DEFAULT with a lot of datasets for testing.
+
+clone repository and install extension for development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ $ git clone git@sissource.ethz.ch:sispub/jupyter-openbis-extension.git
+ $ cd jupyter-openbis-extension
+ $ virtualenv venv
+ $ source venv/bin/activate
+ (venv) $ pip install -e .
+
+The ``-e`` is a shortcut for ``--editable``. This means, it will only
+establish a link to your source folder instead of copying the files.
+When you do any modifications on the jupyter server extension (the
+Python files) you need to restart Jupyter notebook in order to see the
+changes.
+
+If you make modifications on the UI (the Javascript files) you only need
+to reload the page in order the see the effect.
+
+How to extend Jupyter Notebooks is described
+`here <https://jupyter-notebook.readthedocs.io/en/stable/extending/index.html>`__.
+To distribute Jupyter Extensions, read this
+`documentation <https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Distributing%20Jupyter%20Extensions%20as%20Python%20Packages.html#>`__
+carefully.
diff --git a/jupyter-openbis-extension/__init__.py b/jupyter-openbis-extension/__init__.py
index d83477046abe1a933d40e4b4800f5bb73093e7f3..a5ab3f68f1f5e6866052844ef56168b8768a380d 100644
--- a/jupyter-openbis-extension/__init__.py
+++ b/jupyter-openbis-extension/__init__.py
@@ -1,7 +1,7 @@
name = 'jupyter-openbis-extension.server'
__author__ = 'Swen Vermeul'
__email__ = 'swen@ethz.ch'
-__version__ = '0.1.1'
+__version__ = '0.2.0'
def _jupyter_server_extension_paths():
return [{
diff --git a/setup.py b/setup.py
index 868ef0f5592d7c9c6358eda5499eade1d846e9ff..7b7e624bcbdca0848c6a491e74e09cce4d85dcd4 100644
--- a/setup.py
+++ b/setup.py
@@ -11,7 +11,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
setup(
name='jupyter-openbis-extension',
- version= '0.1.1',
+ version= '0.2.0',
author='Swen Vermeul | ID SIS | ETH Zürich',
author_email='swen@ethz.ch',
description='Extension for Jupyter notebooks to connect to openBIS and download/upload datasets, inluding the notebook itself',