docs: update docs on shell support and using packages (#19486)

Shell integration no longer requires setting `SPACK_ROOT`, so we can
simplify the documentation on it. The docs on shell support and using
packages are getting a bit old, and information on `spack load` (which
seems to be everyone's most common way of using packages) is hard to
find.

This PR simplifies the shell documentation to remove SPACK_ROOT, and also
moves some sections around for clearer organization.

- [x] make docs on sourcing setup scripts clearer and simpler

- [x] introduce `spack load` early in the basic usage guide instead of
      burying it in the module docs

- [x] clean up module docs so that spack module tcl loads comes later

- [x] be clear about the different ways to use packages so that the users
      can find the docs better.

Co-authored-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>

1 files changed, 30 insertions, 50 deletions

diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst
index 569e5b94d2..052a028045 100644
--- a/lib/spack/docs/getting_started.rst
+++ b/lib/spack/docs/getting_started.rst
@@ -44,50 +44,50 @@ Getting Spack is easy.  You can clone it from the `github repository
 
 This will create a directory called ``spack``.
 
-^^^^^^^^^^^^^^^^^^^^^^^^
-Add Spack to the Shell
-^^^^^^^^^^^^^^^^^^^^^^^^
+.. _shell-support:
 
-We'll assume that the full path to your downloaded Spack directory is
-in the ``SPACK_ROOT`` environment variable.  Add ``$SPACK_ROOT/bin``
-to your path and you're ready to go:
+^^^^^^^^^^^^^
+Shell support
+^^^^^^^^^^^^^
 
-.. code-block:: console
+Once you have cloned Spack, we recommend sourcing the appropriate script
+for your shell:
 
-   # For bash/zsh users
-   $ export SPACK_ROOT=/path/to/spack
-   $ export PATH=$SPACK_ROOT/bin:$PATH
+.. code-block:: console
 
-   # For tsch/csh users
-   $ setenv SPACK_ROOT /path/to/spack
-   $ setenv PATH $SPACK_ROOT/bin:$PATH
+   # For bash/zsh/sh
+   $ . spack/share/spack/setup-env.sh
 
-   # For fish users
-   $ set -x SPACK_ROOT /path/to/spack
-   $ set -U fish_user_paths /path/to/spack $fish_user_paths
+   # For tcsh/csh
+   $ source spack/share/spack/setup-env.csh
 
-.. code-block:: console
+   # For fish
+   $ . spack/share/spack/setup-env.fish
 
-   $ spack install libelf
+That's it! You're ready to use Spack.
 
-For a richer experience, use Spack's shell support:
+Sourcing these files will put the ``spack`` command in your ``PATH``, set
+up your ``MOUDLEPATH`` to use Spack's packages, and add other useful
+shell integration for :ref:`certain commands <packaging-shell-support>`,
+:ref:`environments <environments>`, and :ref:`modules <modules>`. For
+``bash``, it also sets up tab completion.
 
-.. code-block:: console
+If you do not want to use Spack's shell support, you can always just run
+the ``spack`` command directly from ``spack/bin/spack``.
 
-   # Note you must set SPACK_ROOT
 
-   # For bash/zsh users
-   $ . $SPACK_ROOT/share/spack/setup-env.sh
+^^^^^^^^^^^^^^^^^^
+Check Installation
+^^^^^^^^^^^^^^^^^^
 
-   # For tcsh/csh users
-   $ source $SPACK_ROOT/share/spack/setup-env.csh
+With Spack installed, you should be able to run some basic Spack
+commands.  For example:
 
-   # For fish users
-   $ source $SPACK_ROOT/share/spack/setup-env.fish
+.. command-output:: spack spec netcdf-c
 
-This automatically adds Spack to your ``PATH`` and allows the ``spack``
-command to be used to execute spack :ref:`commands <shell-support>` and
-:ref:`useful packaging commands <packaging-shell-support>`.
+In theory, Spack doesn't need any additional installation; just
+download and run!  But in real life, additional steps are usually
+required before Spack can work in a practical sense.  Read on...
 
 ^^^^^^^^^^^^^^^^^
 Clean Environment
@@ -103,17 +103,6 @@ environment*, especially for ``PATH``.  Only software that comes with
 the system, or that you know you wish to use with Spack, should be
 included.  This procedure will avoid many strange build errors.
 
-
-^^^^^^^^^^^^^^^^^^
-Check Installation
-^^^^^^^^^^^^^^^^^^
-
-With Spack installed, you should be able to run some basic Spack
-commands.  For example:
-
-.. command-output:: spack spec netcdf-c
-
-
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 Optional: Alternate Prefix
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -132,15 +121,6 @@ copy of spack installs packages into its own ``$PREFIX/opt``
 directory.
 
 
-^^^^^^^^^^
-Next Steps
-^^^^^^^^^^
-
-In theory, Spack doesn't need any additional installation; just
-download and run!  But in real life, additional steps are usually
-required before Spack can work in a practical sense.  Read on...
-
-
 .. _compiler-config:
 
 ----------------------