Documentation: spack load/environments prefix inspections (#19961)

As of #18260, `spack load` and `spack env activate` now use
`prefix_inspections` from the modules configuration to decide
how to modify environment variables.

This updates the modules configuration documentation to describe
how to update environment variables with the `prefix_inspections`
section. This also updates the `spack load` and environments
documentation to refer to the new `prefix_inspections` documentation.

3 files changed, 34 insertions, 4 deletions

diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index f846cdabe4..1a73bd0339 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -635,8 +635,10 @@ your path:
    ~/spack/opt/linux-debian7-x86_64/gcc@4.4.7/mpich@3.0.4/bin/mpicc
 
 These commands will add appropriate directories to your ``PATH``,
-``MANPATH``, ``CPATH``, and ``LD_LIBRARY_PATH``.  When you no longer
-want to use a package, you can type unload or unuse similarly:
+``MANPATH``, ``CPATH``, and ``LD_LIBRARY_PATH`` according to the
+:ref:`prefix inspections <customize-env-modifications>` defined in your
+modules configuration.  When you no longer want to use a package, you
+can type unload or unuse similarly:
 
 .. code-block:: console
 
diff --git a/lib/spack/docs/environments.rst b/lib/spack/docs/environments.rst
index 65eec36581..1710ec6b5a 100644
--- a/lib/spack/docs/environments.rst
+++ b/lib/spack/docs/environments.rst
@@ -815,8 +815,10 @@ environment for Spack commands. The arguments ``-v,--with-view`` and
 behavior is to activate with the environment view if there is one.
 
 The environment variables affected by the ``spack env activate``
-command and the paths that are used to update them are in the
-following table.
+command and the paths that are used to update them are determined by
+the :ref:`prefix inspections <customize-env-modifications>` defined in
+your modules configuration; the defaults are summarized in the following
+table.
 
 =================== =========
 Variable            Paths
diff --git a/lib/spack/docs/module_file_support.rst b/lib/spack/docs/module_file_support.rst
index 14925c8590..721b18d5fc 100644
--- a/lib/spack/docs/module_file_support.rst
+++ b/lib/spack/docs/module_file_support.rst
@@ -394,6 +394,32 @@ that are already in the LMod hierarchy.
    For hierarchies that are deeper than three layers ``lmod spider`` may have some issues.
    See `this discussion on the LMod project <https://github.com/TACC/Lmod/issues/114>`_.
 
+.. _customize-env-modifications:
+
+"""""""""""""""""""""""""""""""""""
+Customize environment modifications
+"""""""""""""""""""""""""""""""""""
+
+You can control which prefixes in a Spack package are added to environment
+variables with the ``prefix_inspections`` section; this section maps relative
+prefixes to the list of environment variables which should be updated with
+those prefixes.
+
+.. code-block:: yaml
+
+  modules:
+    prefix_inspections:
+      bin:
+        - PATH
+      lib:
+        - LIBRARY_PATH
+      '':
+        - CMAKE_PREFIX_PATH
+
+In this case, for a Spack package ``foo`` installed to ``/spack/prefix/foo``,
+the generated module file for ``foo`` would update ``PATH`` to contain
+``/spack/prefix/foo/bin``.
+
 """"""""""""""""""""""""""""""""""""
 Filter out environment modifications
 """"""""""""""""""""""""""""""""""""