Merge pull request #1932 from vkarak/doc/improve-tutorial-configuration

[doc] Make basic configuration example more intuitive w.r.t. to modules systems

Author: Vasileios Karakasis

docs/configure.rst

@@ -68,17 +68,17 @@ Each system is a different object inside the ``systems`` section.
 In our example we define three systems, a Mac laptop, Piz Daint and a generic fallback system:
 
 .. literalinclude:: ../tutorials/config/settings.py
-   :lines: 11-89
+   :lines: 11-90
 
 Each system is associated with a set of properties, which in this case are the following:
 
 * ``name``: The name of the system.
   This should be an alphanumeric string (dashes ``-`` are allowed) and it will be used to refer to this system in other contexts.
 * ``descr``: A detailed description of the system.
 * ``hostnames``: This is a list of hostname patterns following the `Python Regular Expression Syntax <https://docs.python.org/3/library/re.html#regular-expression-syntax>`__, which will be used by ReFrame when it tries to automatically select a configuration entry for the current system.
-* ``modules_system``: In our example, this is only defined for Piz Daint and refers to the environment modules system that should be used for loading environment modules on this system.
-  In this case, the classic Tcl implementation of the `environment modules <https://sourceforge.net/projects/modules/files/Modules/modules-3.2.10/>`__.
-  For a complete list of the supported modules systems, see `here <config_reference.html#.systems[].modules_system>`__.
+* ``modules_system``: This refers to the modules management backend which should be used for loading environment modules on this system.
+  Multiple backends are supported, as well as the special ``nomod`` backend which implements the different modules system operations as no-ops.
+  For the complete list of the supported modules systems, see `here <config_reference.html#.systems[].modules_system>`__.
 * ``partitions``: The list of partitions that are defined for this system.
   Each partition is defined as a separate object.
   We devote the rest of this section in system partitions, since they are an essential part of ReFrame's configuration.
@@ -90,7 +90,7 @@ The ``login`` partition refers to the login nodes of the system, whereas the ``g
 Let's pick the ``gpu`` partition and look into it in more detail:
 
 .. literalinclude:: ../tutorials/config/settings.py
-   :lines: 38-58
+   :lines: 39-59
 
 The basic properties of a partition are the following:
 
@@ -132,7 +132,7 @@ In our example, we define environments for all the basic compilers as well as a
 In certain contexts, it is useful to see a ReFrame environment as a wrapper of a programming toolchain (MPI + compiler combination):
 
 .. literalinclude:: ../tutorials/config/settings.py
-   :lines: 90-148
+   :lines: 91-149
 
 Each environment is associated with a name.
 This name will be used to reference this environment in different contexts, as for example in the ``environs`` property of the system partitions.
@@ -154,7 +154,7 @@ Additionally, it allows for logging performance data from performance tests into
 Let's see how logging is defined in our example configuration, which also represents a typical one for logging:
 
 .. literalinclude:: ../tutorials/config/settings.py
-   :lines: 149-184
+   :lines: 150-185
 
 Logging is configured under the ``logging`` section of the configuration, which is a list of logger objects.
 Unless you want to configure logging differently for different systems, a single logger object is enough.

docs/tutorial_advanced.rst

@@ -499,7 +499,7 @@ You can then use those resources transparently from within your test.
 To achieve this in our case, we first need to define a ``memory`` resource in the configuration:
 
 .. literalinclude:: ../tutorials/config/settings.py
-   :lines: 30-51,58-74
+   :lines: 31-52,63-79
    :emphasize-lines: 17-22,32-38
 
 Notice that we do not define the resource for all the partitions, but only for those that it makes sense.
@@ -707,7 +707,7 @@ ReFrame can be used also to test applications that run inside a container.
 First, we need to enable the container platform support in ReFrame's configuration and, specifically, at the partition configuration level:
 
 .. literalinclude:: ../tutorials/config/settings.py
-   :lines: 38-62
+   :lines: 39-63
    :emphasize-lines: 15-24
 
 For each partition, users can define a list of container platforms supported using the :js:attr:`container_platforms` `configuration parameter <config_reference.html#.systems[].partitions[].container_platforms>`__.

docs/tutorial_basics.rst

@@ -325,8 +325,8 @@ Note that you should *not* edit this configuration file in place.
 Here is how the new configuration file looks like with the needed additions highlighted:
 
 .. literalinclude:: ../tutorials/config/settings.py
-   :lines: 10-24,80-101,134-
-   :emphasize-lines: 3-15,31-42
+   :lines: 10-25,81-102,135-
+   :emphasize-lines: 3-16,32-43
 
 Here we define a system named ``catalina`` that has one partition named ``default``.
 This partition makes no use of any `workload manager <config_reference.html#.systems[].partitions[].scheduler>`__, but instead launches any jobs locally as OS processes.
@@ -336,8 +336,8 @@ Notice, how you can define the actual commands for invoking the C, C++ and Fortr
 As soon as a programming environment defines the different compilers, ReFrame will automatically pick the right compiler based on the source file extension.
 In addition to C, C++ and Fortran programs, ReFrame will recognize the ``.cu`` extension as well and will try to invoke the ``nvcc`` compiler for CUDA programs.
 
-Finally, the new system that we defined may be identified by the hostname ``tresa`` (see the :js:attr:`hostnames` configuration parameter).
-This will help ReFrame to automatically pick the right configuration when running on it.
+Finally, the new system that we defined may be identified by the hostname ``tresa`` (see the :js:attr:`hostnames` configuration parameter) and it will not use any environment modules system (see the :js:attr:`modules_system` configuration parameter).
+The :js:attr:`hostnames` attribute will help ReFrame to automatically pick the right configuration when running on it.
 Notice, how the ``generic`` system matches any hostname, so that it acts as a fallback system.
 
 .. note::
@@ -827,8 +827,8 @@ Let's extend our configuration file for Piz Daint.
 
 
 .. literalinclude:: ../tutorials/config/settings.py
-   :lines: 10-45,62-70,77-
-   :emphasize-lines: 16-48,70-101,114-120
+   :lines: 10-46,63-71,78-
+   :emphasize-lines: 17-49,71-102,115-121
 
 
 First of all, we need to define a new system and set the list of hostnames that will help ReFrame identify it.

tutorials/config/settings.py

@@ -13,6 +13,7 @@
             'name': 'catalina',
             'descr': 'My Mac',
             'hostnames': ['tresa'],
+            'modules_system': 'nomod',
             'partitions': [
                 {
                     'name': 'default',