From 5611252344f92f50a82cb355fd4e87cdff481463 Mon Sep 17 00:00:00 2001
From: Rafal Gumienny <guma44@gmail.com>
Date: Wed, 14 Mar 2018 17:15:00 +0100
Subject: [PATCH] docs: SCHWED-3097 More documentation
---
singularity/README.rst | 81 ++++++++++-------------------------
singularity/Singularity.1.7.1 | 10 +++++
2 files changed, 33 insertions(+), 58 deletions(-)
diff --git a/singularity/README.rst b/singularity/README.rst
index 5272a6eab..f3e57b776 100644
--- a/singularity/README.rst
+++ b/singularity/README.rst
@@ -1,8 +1,8 @@
OST Singularity
===============
-Build Singularity image
------------------------
+Building Singularity image
+--------------------------
In order to build OST Singularity image:
@@ -21,77 +21,42 @@ that the image name is `ost.img`.
Available apps
--------------
-OST
-===
+This container includes the following apps:
+ * **OST** - OpenStructure binary
+ * **IPython** - OST-powered iPython shell
+ * **Notebook** - A Jupyter notebook palyground with OST and nglview
+ * **lDDT** - The Local Distance Difference Test
+ * **Molck** - Molecular checker
+ * **ChemdictTool** - Creating or update a compound library
-The OST app exposes OpenStructure binary and can be used to run interactive shell
-and scripts.
-
-To invoke OST shell run:
+To see the help for each individual app run:
.. code-block:: bash
- singularity run --app OST ost.img
-
-In order to run OST script do:
-
-.. code-block:: bash
- singularity run --app OST ost.img <SCRIPT NAME> [SCRIPT OPTIONS]
-
-.. warning::
- If script requires some external files eg. PDBs, they have to be located in the
- path accessible via mounted volumes. By default Singularity mounts $HOME and
- goes to CWD. Thus this sould work as expected out of the box.
-
-One can find a exemplary script (`test_docker.py`) in the <OST ROOT>/docker
-directory. To run it do:
-
-.. code-block::
-
- cd <OST ROOT>/singularity
- singularity run --app OST ost.img ../docker/test_docker.py
+ singularity help --app <APP NAME> <PATH TO OST IMAGE>
-lDDT
-====
+Eg.:
-This app runs the Local Distance Test. To see more details run:
+.. code-block:: bash
-.. code-block::
+ singularity help --app OST ost.img
- cd <OST ROOT>/singularity
- singularity run --app lDDT ost.img
-Molck
-====
+Facilitating the usage
+----------------------
-This app runs the Local Distance Test. To see more details run:
+For each of these apps it is useful to create an alias if they will be
+frequently used. Eg. to create an alias for IPython app one can run:
.. code-block::
- cd <OST ROOT>/singularity
- singularity run --app Molck ost.img
-
-Notebook
-========
+ alias ost_ipython="singularity run --app IPython <PATH TO OST IMAGE>"
-Probably the best way to play with OpenStructure is to run it wihtin the Jupyter
-notebook. In order to so run:
+Then (in the same terminal window) to invoke IPython app one can just type:
.. code-block::
- cd <OST ROOT>/singularity
- singularity run --app Notebook ost.img
-
-Copy the URL to the browser and launch the notebook with OST kernel. This will
-load all necessary OST components just like in the OST shell. We also enabled
-the nglview widget to interactively view molecular structures and trajectories.
-For more details on how to use nglview see `the documentation
-<http://nglviewer.org/nglview/latest/>`_.
-
-
-.. warning::
+ ost_ipython
- As the Singularity mounts $HOME by default Jupyter and Ipython config files
- are moved to separate directories. Proper environmental variables are also set.
- In addition, Jupyter is run in a separate virtualenv to not interact with possibly
- installed host version.
+To make the alias permanent put it into your `.bashrc` file or whatever file you
+use to store the aliases.
\ No newline at end of file
diff --git a/singularity/Singularity.1.7.1 b/singularity/Singularity.1.7.1
index b3c30c75c..240f2ab23 100644
--- a/singularity/Singularity.1.7.1
+++ b/singularity/Singularity.1.7.1
@@ -378,6 +378,16 @@ Useful options when running on remote server:
Default: 8888
The port the notebook server will listen on.
+Copy the URL to the browser and launch the notebook with OST kernel. This will
+load all necessary OST components just like in the OST shell. We also enabled
+the nglview widget to interactively view molecular structures and trajectories.
+For more details on how to use nglview see http://nglviewer.org/nglview/latest/.
+
+As the Singularity mounts $HOME by default Jupyter and Ipython config files
+are moved to separate directories. Proper environmental variables are also set.
+In addition, Jupyter is run in a separate virtualenv to not interact with possibly
+installed host version.
+
To list of all available options:
singularity run --app Notebook <IMAGE> --help
--
GitLab