More doc updates

doc/source/CreatingEnvironments.rst

@@ -0,0 +1,33 @@
+.. _CreatingEnvironment:
+
+Creating and installing new environments
+****************************************
+
+The following instructions are a simplified version of the instructions found in :numref:`Sections %s <NewSiteConfigs_macOS>` and :numref:`%s <NewSiteConfigs_Linux>`, and should work for most systems where spack-stack already has a site configuration, or where minimal configuration is necessary. For more detailed instructions, including how to generate new site configurations and more details of when and how to use external packages, see :numref:`Sections %s <NewSiteConfigs_macOS>` and :numref:`%s <NewSiteConfigs_Linux>`. To chain a new Spack environment to an existing one, such as to test a new package version based on dependencies already installed in the upstream environment, see :numref:`%s <Add_Test_Packages>`.
+
+Run the following steps in the case of a new release on a supported platform, or a fresh install on a local machine. Note that items in "<item>" should be replaced with the appropriate values (site names, etc.). "<site name>" and "<template name>" must match the names of directories found under 'configs/sites/' and 'configs/templates/', respectively; <environment name> is a user-chosen name for the Spack environment.
+
+.. code-block:: console
+
+   # To generate a new spack-stack directory structure, run 'git clone --recurse-submodules https://github.com/JCSDA/spack-stack',
+   # optionally with, e.g., '-b release/1.4.1' to specify the version
+
+   . <path to spack-stack directory>/setup.sh
+
+   spack stack create env --site <site name> --template <template name> --name <environment name>
+
+   cd ${SPACK_STACK_DIR}/envs/<environment name>/
+
+   spack env activate .
+
+   # If not using an existing site configuration, you may wish to modify config files and/or populate them using commands
+   # such as 'spack external find' and 'spack compiler find'.
+   # See https://spack-tutorial.readthedocs.io/en/latest/tutorial_configuration.html
+
+   spack concretize |& tee log.concretize
+
+   spack install [--verbose] [--fail-fast] |& tee log.install
+
+   spack module lmod refresh
+
+   spack stack setup-meta-modules

doc/source/Overview.rst

@@ -22,12 +22,16 @@ spack-stack is maintained by:
 - Cameron Book (@ulmononian) and Mark Potts (@mark-a-potts), EPIC
 
 ===============
-Getting Started
+Getting started
 ===============
 
-In order to **access an existing spack-stack installation** on a given system, see the instructions in :numref:`Section %s <UsingSpackEnvironments>`. Ready-to-use spack-stack installations are available on a number of HPC and cloud platforms. A list of those platforms, along with special instructions and caveats for each, can be found in :numref:`Section %s <Preconfigured_Sites>`.
+If you wish to **access an existing spack-stack installation** on a given system, such as to load packages and compile and run a UFS or JEDI application, see the instructions in :numref:`Section %s <UsingSpackEnvironments>`. Ready-to-use spack-stack installations are available on a number of HPC and cloud platforms. A list of those platforms, along with special instructions and caveats for each, can be found in :numref:`Section %s <Preconfigured_Sites>`.
 
-If you wish to **create a new site configuration** in order to create a new spack-stack installation, see the instructions in :numref:`Section %s <NewSiteConfigs>`.
+If you wish to quickly **create a new spack-stack environment (stack installation)**, either on a personal machine or on a supported platform where you are the maintainer, see :numref:`Section %s <CreatingEnvironment>`.
+
+If you wish to **chain a new spack-stack environment to an existing installation**, such as to test a new package version on one of our supported HPC or cloud platforms based on already installed dependencies, see :numref:`Section %s <Add_Test_Packages>`.
+
+If you wish to **create a new site configuration** on a not-yet supported machine, see the instructions in :numref:`Section %s <NewSiteConfigs>`.
 
 .. note::
    As spack-stack is intended to support NOAA EMC, JCSDA, and EPIC applications, users seeking to install software for other purposes, such as developing non-NOAA/JCSDA/EPIC applications, even those that use weather-related libraries, are recommended to simply use `Spack <https://github.com/spack/spack>`_ instead.

doc/source/index.rst

@@ -1,6 +1,6 @@
 .. spack-stack documentation master file
 
-Table of Contents
+Table of contents
 =================
 
 .. toctree::
@@ -10,8 +10,9 @@ Table of Contents
    Overview
    UsingSpackEnvironments
    PreConfiguredSites
-   NewSiteConfigs
+   CreatingEnvironments
    AddingTestPackages
+   NewSiteConfigs
    BuildingContainers
    Environments
    SpackStackExtension