Documentation for modules configuration options (#1685)

This PR add documentation for the `suffixes` and `hash_length` options
for modules.yaml.

This resolves #1416.

1 files changed, 35 insertions, 0 deletions

diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index bbedfff3fc..306d64409d 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -1333,6 +1333,41 @@ load two or more versions of the same software at the same time.
 .. note::
    The ``conflict`` option is ``tcl`` specific
 
+The names of environment modules generated by spack are not always easy to
+fully comprehend due to the long hash in the name. There are two module
+configuration options to help with that. The first is a global setting to
+adjust the hash length. It can be set anywhere from 0 to 32 and has a default
+length of 7. This is the representation of the hash in the module file name and
+does not affect the size of the package hash. Be aware that the smaller the
+hash length the more likely naming conflicts will occur. The following snippet
+shows how to set hash length in the module file names:
+
+.. code-block:: yaml
+
+   modules:
+     tcl:
+       hash_length: 7
+
+To help make module names more readable, and to help alleviate name conflicts
+with a short hash, one can use the ``suffixes`` option in the modules
+configuration file. This option will add strings to modules that match a spec.
+For instance, the following config options,
+
+.. code-block:: yaml
+
+   modules:
+     tcl:
+       all:
+         suffixes:
+           ^python@2.7.12: 'python-2.7.12'
+           ^openblas: 'openblas'
+
+will add a ``python-2.7.12`` version string to any packages compiled with
+python matching the spec, ``python@2.7.12``. This is useful to know which
+version of python a set of python extensions is associated with. Likewise, the
+``openblas`` string is attached to any program that has openblas in the spec,
+most likely via the ``+blas`` variant specification.  
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 Regenerating Module files
 ^^^^^^^^^^^^^^^^^^^^^^^^^