Merge branch 'main' into f/pin-mods

.github/workflows/tests.yml

@@ -21,13 +21,13 @@ jobs:
         python-version: [3.8, 3.9, 3.12]
         spack-version: [0.21.2, develop]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Checkout Spack
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         repository: spack/spack
         ref: ${{ matrix.spack-verions }}
@@ -49,13 +49,13 @@ jobs:
       matrix:
         python-version: [3.9]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Checkout Spack
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         repository: spack/spack
         path: spack
@@ -80,13 +80,13 @@ jobs:
         python-version: [3.8, 3.9]
         spack-version: [0.21.2, develop]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Checkout Spack
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         repository: spack/spack
         ref: ${{ matrix.spack-verions }}

.gitignore

@@ -20,3 +20,4 @@ __pycache__
 Configuring
 .tmp/
 *.swp
+*.DS_*

check.py

@@ -6,16 +6,18 @@
 # for more details.
 
 """
-a script to make sure minimum requirements for spack-manager 
+a script to make sure minimum requirements for spack-manager
 are met.
 
 - [email protected] or higher
 """
 import sys
 
+
 def check_spack_manager_requirements():
-    if sys.version_info < (3,8):
+    if sys.version_info < (3, 8):
         raise ValueError("Spack-Manager requires Python 3.8 or higher.")
 
+
 if __name__ == "__main__":
     check_spack_manager_requirements()

docs/conf.py

@@ -1,42 +1,37 @@
-extensions = ['myst_parser']
+extensions = ["myst_parser"]
 myst_heading_anchors = 3
-templates_path = ['_templates']
-master_doc = 'index'
-project = u'Spack-Manager'
-copyright = u'Phil Sakievich'
-author = u'Phil Sakievich'
-version = u'0.1'
-release = u'0.1'
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-pygments_style = 'sphinx'
+templates_path = ["_templates"]
+master_doc = "index"
+project = "Spack-Manager"
+copyright = "Phil Sakievich"
+author = "Phil Sakievich"
+version = "0.1"
+release = "0.1"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+pygments_style = "sphinx"
 todo_include_todos = False
 numfig = True
-numfig_format = {'figure': '%s', 'table': '%s', 'code-block': '%s'}
-html_theme = 'sphinx_rtd_theme'
+numfig_format = {"figure": "%s", "table": "%s", "code-block": "%s"}
+html_theme = "sphinx_rtd_theme"
 html_static_path = []
-html_theme_options = {
-    'navigation_depth': 3
-}
+html_theme_options = {"navigation_depth": 5}
 html_show_sourcelink = True
 html_show_copyright = False
-htmlhelp_basename = 'spack-manager-doc'
-latex_elements = {
-}
+htmlhelp_basename = "spack-manager-doc"
+latex_elements = {}
 latex_documents = [
-    (master_doc, 'spack-manager.tex', u'Spack-Manager Documentation',
-     author, 'manual'),
-]
-man_pages = [
-    (master_doc, 'spack-manager', u'Spack-Manager Documentation',
-     [author], 1)
+    (master_doc, "spack-manager.tex", "Spack-Manager Documentation", author, "manual")
 ]
+man_pages = [(master_doc, "spack-manager", "Spack-Manager Documentation", [author], 1)]
 texinfo_documents = [
-    (master_doc, 'spack-manager', u'Spack-Manager Documentation',
-     author, 'Spack-Manager', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "spack-manager",
+        "Spack-Manager Documentation",
+        author,
+        "Spack-Manager",
+        "One line description of project.",
+        "Miscellaneous",
+    )
 ]
-source_suffix = {
-    '.rst': 'restructuredtext',
-    '.txt': 'markdown',
-    '.md': 'markdown',
-}
+source_suffix = {".rst": "restructuredtext", ".txt": "markdown", ".md": "markdown"}

docs/general/spack_manager_structure.rst

@@ -0,0 +1,49 @@
+Spack-Manager Structure
+=======================
+
+Spack-Manager is a Spack extension that provides a way for software applications
+to configure their usage of spack.
+
+.. figure:: ./application-workflow.png
+   :width: 100%
+
+   An example of generalized infrastructure requirements that are common across HPC and scientific computing applications. Spack-Manager's goal is to empower these types of infrastructures while still allowing application teams to drive the details.
+
+The code of Spack-Manager is independent of each individual application and each
+application code needs to configure a Spack-Manager `Project` to tell Spack-Manager how to work
+with their application.
+
+.. figure:: ./Spack-Manager-Org.png
+   :width: 50%
+
+   Spack-Manager is designed to provide an abstraction that can support multiple application teams. Each team develops a Project that can be registered with an instance of Spack-Manager.
+
+A `Project` at its core is simply a collection of `spack configuration files`_ and `spack package repositories`_.
+A few other optional hooks will be discussed below.
+
+The configuration files in a `Project` are organized based on the configuration bifurcations that the projects supports.
+These are called `Machines` based on the guiding principle that spack configurations typically have to be
+changed when the machine/system is changed.
+
+`Projects` can be registered with Spack-Manager by adding them to the `spack-manager.yaml` configuration file.
+This file lives in the Spack-Manager directory and controls settings for `Spack-Manager` and the `Projects` that
+are registered.
+
+.. code-block:: yaml
+
+   spack-manager:
+     projects:
+       - /path/to/project_a
+         default_view: False
+       - $HOME/project_b
+
+Information on configuring a new `Project` can be found in the system administrator profile documentation `here`_.
+
+.. figure:: ./ApplicationSpace.png
+   :width: 100%
+
+   The end goal of many code application and DevOps teams is to efficiently span the space of platform permutations and project variations.
+
+.. _spack configuration files: https://spack.readthedocs.io/en/latest/configuration.html
+.. _spack package repositories: https://spack.readthedocs.io/en/latest/repositories.html
+.. _here: https://sandialabs.github.io/spack-manager/user_profiles/system_admins/creating_a_project.html

docs/index.rst

@@ -10,6 +10,13 @@ A given software project typically has multiple configurations across many machi
 Spack-Manager is quite literal in its name, in that it provides a way to manage and organize these configurations
 across multiple machines, and multiple projets.
 
+.. figure:: ./Spack-To-Applications.png
+   :width: 75%
+
+   Spack is serving the package management needs of thousands of software packages.
+   However, individual application teams wish to harness the power of Spack for their individual applications specific needs.
+   This naturally leads to redundant, similar workflows.
+
 The intent of this project is to maintain as thin of a buffer as possible between software packages and Spack, and to be pushing ideas and workflow
 improvements back to Spack on a regular basis to reduce the code that is maintained here.
 As such we do not try to fully mask Spack's workflow or commands from users, but rather expose them at a level appropriate for the user type.
@@ -24,6 +31,11 @@ decreases as the user becomes further removed from the build process.  The three
 - Code developers (some basics about Spack are required, but much of the workflow can be scripted away)
 - Analysts (zero exposure to Spack)
 
+.. figure:: ./ProfilePyramids.png
+   :width: 70%
+
+   Population size of each profile is inverserly proportional to the Spack knowledge required for their roles
+
 Separate documentation exists for each of these user profiles.
 
 .. toctree::
@@ -55,5 +67,4 @@ Additional details about the philosophy, and general knowledge can be found in t
 .. toctree::
    :maxdepth: 3
 
-   general/FAQ
    general/general