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.md b/README.md
index 130717de33680951cac6d2625826828d601903c6..103f79d2eb5e9113bc63fce1332138b3eac3747b 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,43 +15,10 @@ 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
-```
+## Create a configuration file
-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:
+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:
@@ -83,11 +31,10 @@ 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):
+**Note 2**: Place this file in any of these directories (on Mac OS X):
```
/Users/your_username/jupyter-openbis-extension/notebooks
@@ -96,102 +43,77 @@ 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
-Now you are **ready to launch jupyter notebook!**
+Now you are ready to launch Jupyter notebook:
```
-$ jupyter notebook
+$ jupyter notebook --no-browser
```
-Observe the terminal. It should tell you which server(s) have been successfully connected (and which not):
+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
-Cannot establish connection to: https://localhost:8443
+Successfully connected to: https://localhost:8443
Registered: https://openbis.example.com
-Successfully connected to: https://openbis.example.com
```
-**Congratulations!** You can retry non-successful connections later, directly from the GUI.
-
+**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
+$ 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/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/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
+```
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/openbis-connections.yaml b/openbis-connections.yaml
index 754cd1c4c91dfe88e34e94d6368a2e36304705da..056a708b785be83beaafbe0eaf1a3f23ce1202f9 100644
--- a/openbis-connections.yaml
+++ b/openbis-connections.yaml
@@ -2,8 +2,7 @@ connections:
- name: local test openBIS instance
url: https://localhost:8443
verify_certificates: false
- username: username
- password: password
+ username: admin
- name: vagrant openBIS instance
url: https://localhost:8122
verify_certificates: false
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',