diff --git a/README.md b/README.md
index 130717de33680951cac6d2625826828d601903c6..5f46f06b788a48004170fb3a70017e4e14432141 100644
--- a/README.md
+++ b/README.md
@@ -6,25 +6,6 @@ The jupyter-openbis-extension needs at least **Python 3.3** in order to run. The
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.
-## 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.
## Install the extension
@@ -34,41 +15,8 @@ If you haven't done yet: download the latest jupyter-openbis-extension from pip.
pip install --upgrade jupyter-openbis-extension
```
-or, if you would like to develop:
-```
-$ 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 .
-(venv) $ jupyter serverextension enable --py jupyter-openbis-extension
-(venv) $ jupyter nbextension install --py jupyter-openbis-extension --user --symlink
-(venv) $ jupyter nbextension enable jupyter-openbis-extension --user --py
-```
-
-**Register the Jupyter server extension** which will communicate both with openBIS and the notebook:
-```
-jupyter serverextension enable --py jupyter-openbis-extension
-```
-
-**Register the notebook extension**, the client side of the Jupyter notebook, which will communicate with the server extension via AJAX calls:
-
-```
- jupyter nbextension install --py jupyter-openbis-extension --user
-```
-If you are developing, you should consider creating a link to the JavaScript source instead:
-
-```
- jupyter nbextension install --py jupyter-openbis-extension --user --symlink
-```
-
-Finally, activate the notebook extension.
-
-```
-jupyter nbextension enable jupyter-openbis-extension --user --py
-```
**Create a configuration file**: `~/.jupyter/openbis-connections.yaml` It should contain connection information to your server(s), for example:
@@ -83,9 +31,8 @@ connections:
url : https://openbis.example.com
verify_certificates : true
username : username
- password : password
```
-**Note 1**: You do not need the usernames or passwords anymore. With the current version, you are able to enter username and password directly from within a Jupyter notebook.
+**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**: You can place this file in any of these directories (on Mac OS X):
@@ -96,7 +43,12 @@ connections:
/usr/local/etc/jupyter
/etc/jupyter
```
-These directories are produced by Jupyters' `nb_server_app.config_file_paths` method.
+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
@@ -124,74 +76,46 @@ 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 `~/.jupyter/jupyter_notebook_config.json` and `~/.jupyter/nbconfig/notebook.json`. The symbolic link in `~/Library/Jupyter/nbextension/` (Mac OS X) should have been removed too. If not, you can remove it manually.
-
-
-
-## Manual installation (if above should fail)
+This should remove the registrations in the paths listed by the
-### Install the Python module(s)
-- clone the project:
```
-git clone git@sissource.ethz.ch:sispub/jupyter-openbis-extension.git
+$ jupyter --paths
```
-- cd into the extension `cd jupyter-openbis-extension`
-- install the python module normally: `pip install .`
-- or, for development, install just a symbolic link: `pip install -e .`
-- this extension needs Jupyter and pyBIS 1.7.2 in order to run, so it will load / upgrade it if not yet present
-- the jupyter-openbis-extension needs at least Python 3.3 in order to run. Therefore, your Jupyter notebook server (but not the kernel!) needs to run under at least Python 3.3 too.
+command.
-### Register the Jupyter Notebook Server Extension (server-side, as the name suggests)
-- in the terminal, enter the following:
-``
-jupyter serverextension enable --py jupyter-openbis-extension
-``
+## Development with Vagrant
-- OR (1) register it manually:
-- open the file `~/.jupyter/jupyter_notebook_config.py`
-- add the following:
+If you want to use a predefined development environment, follow these steps:
-```
-c.NotebookApp.server_extensions = [
- 'jupyter-openbis-extension.server'
-]
-```
+1. Install latest version of VirtualBox (<https://www.virtualbox.org>)
-- OR (2) register it in `~/.jupyter/jupyter_notebook_config.json` manually, if the automatic registration fails for some reasons:
-```
-{
- "NotebookApp": {
- "nbserver_extensions": {
- "jupyter-openbis-extension.server": true
- }
- }
-}
-```
+2. Install latest version of Vagrant (<https://www.vagrantup.com/downloads.html>)
-### Register the Jupyter Notebook Extension (client-side)
+3. vagrant plugin install vagrant-vbguest vagrant-notify-forwarder vagrant-disksize
+
+4. cd vagrant
-Inside the folder `~/Library/Jupyter/nbextension/` (Mac OS X) create a symbolic **link to the folder that contains the Java Script**:
+5. vagrant up
-```
-ln -s /path/to/jupyter-openbis-extension/nbextension/dialog.js jupyter-openbis-extension
-```
-In the file `~/.jupyter/nbconfig/notebook.json` the JavaScript gets activated like this:
+After the setup is complete, you'll have
-```
-{
- "load_extensions": {
- "jupyter-openbis-extension/dialog": true
- }
-}
-```
-**Check** that the nbextension has been installed and activated:
+* 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
```
-$ jupyter nbextension list
-Known nbextensions:
- config dir: /Users/your-username/.jupyter/nbconfig
- notebook section
- jupyter-openbis-extension/dialog enabled
- - Validating: OK
+$ 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.
\ No newline at end of file
diff --git a/how_to_install_the_extension_manually.md b/how_to_install_the_extension_manually.md
new file mode 100644
index 0000000000000000000000000000000000000000..ba91a5826eff2b74007b3ac3ee1c65ab93b51ec6
--- /dev/null
+++ b/how_to_install_the_extension_manually.md
@@ -0,0 +1,94 @@
+# Installing the extension manually
+
+
+**Register the Jupyter server extension** which will communicate both with openBIS and the notebook:
+
+```
+jupyter serverextension enable --py jupyter-openbis-extension
+```
+
+**Register the notebook extension**, the client side of the Jupyter notebook, which will communicate with the server extension via AJAX calls:
+
+```
+ jupyter nbextension install --py jupyter-openbis-extension --user
+```
+If you are developing, you should consider creating a link to the JavaScript source instead:
+
+```
+ jupyter nbextension install --py jupyter-openbis-extension --user --symlink
+```
+
+Finally, activate the notebook extension.
+
+```
+jupyter nbextension enable jupyter-openbis-extension --user --py
+```
+
+
+## Manual installation (if above should fail)
+
+### Install the Python module(s)
+- clone the project:
+```
+git clone git@sissource.ethz.ch:sispub/jupyter-openbis-extension.git
+```
+- cd into the extension `cd jupyter-openbis-extension`
+- install the python module normally: `pip install .`
+- or, for development, install just a symbolic link: `pip install -e .`
+- this extension needs Jupyter and pyBIS 1.7.2 in order to run, so it will load / upgrade it if not yet present
+- the jupyter-openbis-extension needs at least Python 3.3 in order to run. Therefore, your Jupyter notebook server (but not the kernel!) needs to run under at least Python 3.3 too.
+
+### Register the Jupyter Notebook Server Extension (server-side, as the name suggests)
+- in the terminal, enter the following:
+
+``
+jupyter serverextension enable --py jupyter-openbis-extension
+``
+
+- OR (1) register it manually:
+- open the file `~/.jupyter/jupyter_notebook_config.py`
+- add the following:
+
+```
+c.NotebookApp.server_extensions = [
+ 'jupyter-openbis-extension.server'
+]
+```
+
+- OR (2) register it in `~/.jupyter/jupyter_notebook_config.json` manually, if the automatic registration fails for some reasons:
+```
+{
+ "NotebookApp": {
+ "nbserver_extensions": {
+ "jupyter-openbis-extension.server": true
+ }
+ }
+}
+```
+
+### Register the Jupyter Notebook Extension (client-side)
+
+Inside the folder `~/Library/Jupyter/nbextension/` (Mac OS X) create a symbolic **link to the folder that contains the Java Script**:
+
+```
+ln -s /path/to/jupyter-openbis-extension/nbextension/dialog.js jupyter-openbis-extension
+```
+In the file `~/.jupyter/nbconfig/notebook.json` the JavaScript gets activated like this:
+
+```
+{
+ "load_extensions": {
+ "jupyter-openbis-extension/dialog": true
+ }
+}
+```
+**Check** that the nbextension has been installed and activated:
+
+```
+$ jupyter nbextension list
+Known nbextensions:
+ config dir: /Users/your-username/.jupyter/nbconfig
+ notebook section
+ jupyter-openbis-extension/dialog enabled
+ - Validating: OK
+```