Add modules section

conf.py

@@ -56,9 +56,9 @@ author = 'Michael'
 # built documents.
 #
 # The short X.Y version.
-version = '3.6.2'
+version = '3.7.0'
 # The full version, including alpha/beta/rc tags.
-release = '3.6.2'
+release = '3.7.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

environment/modules.rst

+Modules
+=======
+
+Environment modules are a well established means of switching software versions
+in the HPC world. The base operating system usually provides the most stable
+and secure updates for specific software such as R or python. However, with
+most of the research software out there, it's sometimes necessary to use
+a specific major version of the software. For example, if some script,
+toolbox, or library depends on it.
+
+If you need a software that differs from the operating system base you can let
+us know and we try to build and deploy that software for you through the module
+system. Notable examples are Matlab and R.
+
+Quick Start
+-----------
+
+**List available** modules with program:`module avail`:
+
+**Activate** a module with program:`module load NAME[/OPTIONAL_VERSION]`.
+
+
+Details
+-------
+
+On every Linux there are two environment variables that determine the software
+reachable to you: `PATH` and `LD_LIBRARY_PATH`.
+In most cases environment modules are simply modifying these two variables. For
+instance, if your `PATH` contains `/opt/software/matlab/R2017b/bin` then
+everything available in that folder will be available in your shell and when
+you run program:`matlab` it will probably be the one found in there:
+
+.. code:
+
+   [krause@ood-43 ~] which matlab
+   /usr/local/bin/matlab
+   [krause@ood-43 ~] echo $PATH
+   /home/mpib/krause/bin:/home/mpib/krause/.local/bin:/usr/bin:/usr/sbin:/opt/bin:/usr/local/bin:/usr/bin:/bin
+   [krause@ood-43 ~] module load matlab
+   [krause@ood-43 ~] which matlab
+   /opt/matlab/R2017b/bin//matlab
+   [krause@ood-43 ~] echo $PATH
+   /opt/matlab/R2017b/bin/:/home/mpib/krause/bin:/home/mpib/krause/.local/bin:/usr/bin:/usr/sbin:/opt/bin:/usr/local/bin:/usr/bin:/bin
+
+
+The source definition for an environment file is pretty straight forward, you can have a look in :program:`/opt/environment/modules` to see what they do.
+
+It's possible to conflict with other modules. For example, if you were to load :program:`mrtrix3` and :program:`mrtrix3tissue` you would get an error, because only one implementation of mrtrix3 should be active:
+
+
+.. code:
+
+   [krause@master ~] module load mrtrix3
+   [krause@master ~] module load mrtrix3tissue
+   mrtrix3tissue/5.2.8(13):ERROR:150: Module 'mrtrix3tissue/5.2.8' conflicts with the currently loaded module(s) 'mrtrix3/rc3'
+   mrtrix3tissue/5.2.8(13):ERROR:102: Tcl command execution failed: conflict        "mrtrix3"
+
+
+To deactivate a module, simply end the shell (a module activation is not persistent) or run :program:`module unload mrtrix3`.
+
+To list all currently active modules, you can use :program:`module list`.
+
+Caveats
+-------
+
+Software built in :path:`/opt/software` is prone to break after operating
+system upgrades. In cases where the software is compiled statically (R) or
+where the software ships their own shared libraries (Matlab), everything will
+continue to work. In same cases where software is delivered as a tarball
+(freesurfer) it's entirely possible that some internal program will stop
+working at some point. This is an inherent problem of shipping dynamically
+built software outside of the operating system's own package manager and
+nothing we can fix (see the section for Singularity for a different approach to
+solve this problem).

index.rst

@@ -4,6 +4,11 @@ Welcome to Tardis's documentation!
 Changelog
 =========
 
+3.7.0 (02.04.2020)
+  + introduce the /data folder
+  + added section about singularity
+  + finally documented environment modules
+
 3.6.2 (17.12.2019)
   + new memory defaults for compiled spm12
 
@@ -72,6 +77,14 @@ List of Contents
    pbs/resources
    pbs/dependencies
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Environment
+
+   environment/modules
+   environment/singularity
+   environment/unix
+
 .. toctree::
    :maxdepth: 1
    :caption: Software
@@ -83,7 +96,6 @@ List of Contents
    software/matlab
    software/python
    software/r
-   software/unix
 
 .. toctree::
    :maxdepth: 1