update docs

docs/index.md

@@ -31,7 +31,7 @@ uenv start $SCRATCH/images/gromacs.sqfs:/user-environment
 Will start a new shell with the environment `gromacs.sqfs` mounted at `/user-environment`.
 
 ```bash
-uenv start $SCRATCH/images/gromacs.sqfs,debugger.sqfs:/user-tools
+uenv start $SCRATCH/images/gromacs.sqfs debugger.sqfs:/user-tools
 ```
 
 Will start a new shell with the environment `gromacs.sqfs` mounted at `/user-environment`, and `debugger.sqfs` mounted at `/user-tools`
@@ -57,30 +57,42 @@ uenv status
 
 ### Modules
 
-If a loaded uenv provides modules, these can be enabled using the `module use` command.
+Uenv can be configured to provide modules, however not all uenv provide modules.
+If a uenv provides modules, they are not directly available for querying and accessing using `module avail` or `module load` etc.
+
+To find information about which running uenv provide modules, and whether modules have been activated:
 
 ```bash
-uenv module [environments]
+uenv modules
 ```
 
-where `[environments]'` is an optional list of environments to load.
+If a loaded uenv provides modules, these can be enabled using the `modules use` command:
+
+```bash
+uenv modules use [environments]
+```
+
+where `[environments]'` is a list of uenv whose modules are to be made available.
+
+!!! info
+    If `[environments]` is not provided, the module files from all loaded uenv that provide modules will be made available.
 
-Use the modules provided by `/user-environment`:
+**Example 1**: use the modules provided by `/user-environment`:
 ```bash
 uenv modules use /user-environment
 ```
 
-Use the modules provided by the loaded uenv with name `gromacs/2023`:
+**Example 2**: use the modules provided by the loaded uenv with name `gromacs/2023`:
 ```bash
 uenv modules use gromacs/2023
 ```
 
-Use the modules provided by the main uenv
+**Example 3**: the modules provided by all loaded uenv that provide modules:
 ```bash
 uenv modules use
 ```
 
-Use the modules provided by the uenv mounted at `/user-tools` and the uenv with name `gromacs/2023`
+**Example 4**: use the modules provided by the uenv mounted at `/user-tools` and the uenv with name `gromacs/2023`
 ```bash
 uenv modules use gromacs/2023 /user-tools
 ```

uenv-impl

@@ -155,14 +155,18 @@ class environment:
         elif ("UENV_MOUNT_FILE" in os.environ) and ("UENV_MOUNT_POINT" in os.environ):
             mnt = os.environ.get("UENV_MOUNT_POINT")
 
-            # TODO: check whether an image has been mounted at UENV_MOUNT_POINT?
-            #   findmnt -n --mountpoint /user-environment
-            # should return something like:
-            #   /user-environment /dev/loop12 squashfs ro,nosuid,nodev,relatime
             self._uenvs = [uenv(pathlib.Path(mnt))]
 
+        # TODO: check whether an image has been mounted at each _uenv[]
+        #   findmnt -n --mountpoint /user-environment
+        #   findmnt -n --mountpoint {str(_uenv[i]).mount}
+        # should return something like:
+        #   /user-environment /dev/loop12 squashfs ro,nosuid,nodev,relatime
 
-    # TODO: these need to parse env variables for multi-mount points
+
+    # Read environment variables set by previous calls to uenv, that record which
+    # views and modules have been loaded.
+    # Additionally read the vcluster name, if set.
     def load_status(self):
         modules = None
         if os.environ.get('UENV_MODULE_PATH') is not None:
@@ -527,22 +531,26 @@ def generate_modules_command(args, env):
         return shell_noop
 
     # generate a list of all the mounted environments that provide modules
-    module_envs = [{"name": e.name, "mount": e.mount, "modules": e.modules, "loaded": e.modules_loaded}
+    module_envs = [
+        {"name": e.name, "mount": e.mount, "modules": e.modules, "loaded": e.modules_loaded}
             for e in env.uenvs
                 if (e.modules is not None) and e.is_native_mounted]
 
     print_debug(f"modules are provided by {module_envs}")
 
-    # No use command - print the status of the modules
+    # No use command, i.e. the folloing CLI command was made:
+    #   uenv modules
+    # print the status of the modules
     if not args.modules_command=="use":
         if len(module_envs)==0:
             return "echo 'no loaded environments provide modules'"
         output = ["echo 'the following loaded uenv provide modules:'"]
+        loaded = colorize("(loaded)", "yellow")
         for e in module_envs:
             name = e["name"]
             mount = e["mount"]
             if e["loaded"]:
-                output.append(f"echo '  {name}:{mount} (loaded)'")
+                output.append(f"echo '  {name}:{mount} {loaded}'")
             else:
                 output.append(f"echo '  {name}:{mount}'")
             output.append(shell_noop)