Merge branch 'doc/anaconda_installation' into 'master'

instructions to install using anaconda

See merge request detectors/pycalibration!94

docs/source/conf.py

@@ -137,7 +137,7 @@ todo_include_todos = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+# html_theme = ''
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/installation.rst

@@ -2,20 +2,19 @@ Installation
 ============
 
 Installation of the European XFEL Offline Calibration tools is best
-done into a Karabo_ Python_ environment. However, there are no explicit
-Karabo dependencies, so any Python3 environment is capable of running
-the tools.
+done into an anaconda/3 environment using Maxwell_ cluster. However, there are no explicit
+dependencies, so any Python3 environment is capable of running the tool.
 
-A more detailed step-by-step intruction can be found in the :ref:`tutorial`.
+A more detailed step-by-step instruction can be found in the :ref:`tutorial`.
 
-Prerequisites
--------------
+Package Requirements
+--------------------
 
-Prerequisites can be categorized into three types:
+Requirements can be categorized into three types:
 
-1. those required to run the the general tool chain,
-2. those required by the notebooks themselves,
-3. and those required to run notebooks concurrently on a HPC cluster.
+1. Those required to run the the general tool chain,
+2. Those required by the notebooks themselves,
+3. Those required to run notebooks concurrently on a HPC cluster.
 
 Categories 1+2 are usually Python modules, as given in the `requirements.txt`
 file found in the root directory. Additionally, PyDetLib_ is required.
@@ -29,27 +28,49 @@ parameter when executing `xfel-calibrate`.
 .. _Karabo: https://in.xfel.eu/readthedocs/docs/karabo/en/latest/
 .. _SLURM: https://slurm.schedmd.com
 .. _PyDetLib: https://in.xfel.eu/readthedocs/docs/pydetlib/en/latest/
+.. _Maxwell: https://confluence.desy.de/display/IS/Running+Jobs+on+Maxwell
 
-Installing
-----------
+Installation using Anaconda
+---------------------------
 
-If you are installing into a Karabo environment make sure it is enabled
-by sourcing the activate file in the Karabo path::
+First you need to load the anaconda/3 environment through::
 
-    source karabo/activate
-    
-For other python enviroments, this step can be skipped. The package for the offline
-calibration can be obtained from the git repository::
+    1. module load anaconda/3 
 
-    git clone https://git.xfel.eu/gitlab/detectors/pycalibration.git
+If installing into other python enviroments, this step can be skipped. 
 
-You can then install all prerequisites and this tool chain by running::
+Then the package for the offline calibration can be obtained from the git repository::
 
-    pip install -r requirements.txt .
-    
-in th emain directoy pycalibration. 
-After installation, you should adjust the :ref:`configuration` and settings in the folder
-xfel-calibrate to match your environment.
+    2. git clone https://git.xfel.eu/gitlab/detectors/pycalibration.git
+
+Home directory
+++++++++++++++
+
+You can then install all requirements of this tool chain in your home directory by running::
+
+    3. pip install -r requirements.txt . --user
+
+in pycalibration's root directory.
+
+After installation, you should make sure that the home directory is in the PATH environment variable::
+
+    4. PATH=/home/<username>/.local/bin:$PATH
+
+Preferred directory
++++++++++++++++++++
+
+Alternatively, you can install all requirements in a directory of your preference by::
+
+    3. mkdir /gpfs/exfel/data/scratch/<username>/<directory-name>
+       pip install --target=/gpfs/exfel/data/scratch/<username>/<directory-name> -r requirements.txt .
+
+and it is important to make sure that the installed requirements are in the PATH environment::
+
+    4. PATH=/gpfs/exfel/data/scratch/<username>/<directory-name>/bin:$PATH
+
+
+After this make sure that you adjust the :ref:`configuration` and settings in the xfel-calibrate
+folder to match your environment.
 
 The tool-chain is then available via the::
 
@@ -57,26 +78,43 @@ The tool-chain is then available via the::
     
 command.
 
+
+Installation using karabo
++++++++++++++++++++++++++
+
+If required, one can install into karabo environment. The difference would be to 
+first source activate the karabo envrionment::
+
+    1. source karabo/activate
+
+then after cloning the offline calibration package from git, the requirements can be installed through::
+
+    3. pip install -r requirements.txt .
+
 Development Installation
 ------------------------
 
-For a development installation, which automatically picks up (most) changes,
-first install the dependencies as above, but then install the tool-chain 
-separately in development mode::
+For a development installation in your home directory, which automatically 
+picks up (most) changes, first install the dependencies as above, 
+but then install the tool-chain separately in development mode::
 
-   pip install -e .
-   
+   pip install -e . --user
 
+.. note:: Using "- -target" for development installation in a preferred directory can lead to errors.
+
+.. note:: For development installation in karabo environment "- -user" is not needed.
 
 Installation of New Notebooks
 -----------------------------
 
-To install new, previously untracked notebooks repeat the installation of
-the the tool-chain, without prerequisites, from the package base directory::
+To install new, previously untracked notebooks in the home directory, 
+repeat the installation of the the tool-chain, without requirments, 
+from the package base directory::
 
-    pip install --upgrade .
+    pip install --upgrade . --user
     
-Or, in case you are activily developing::
+Or, in case you are actively developing::
+
+    pip install -e . --user
 
-    pip install -e .
 

requirements.txt

@@ -15,5 +15,8 @@ gitpython
 karabo_data
 sklearn
 prettytable
+jupyter
+jupyter_console
+sphinx == 1.4.5
 ./cal_tools
 .