polish documentation, supress output from git_clone command

mpsd-software-environment.py

@@ -315,15 +315,14 @@ def set_up_logging(loglevel="warning", file_path=None):
     )
 
 
-def get_available_toolchains_upstream(release: str) -> List[str]:
-    """Given a release, return the available toolchains available in
-    the spack-environment's repository [1].
+def get_available_toolchains(release: str) -> List[str]:
+    """Given a release, return the available toolchains.
 
-    This may be different than what is available locally: Once we have checked
-    out a branch of the repository (for example under the name of dev-23a), we
-    are stuck to the toolchains available in there. (Unless we started to
-    update the dev-23a repository with a pull - we probably do not want to do
-    that.)
+    This is based on the spack-environment's repository [1]. For this function
+    to succeed, we need to have Internet access etc.
+
+    We use a temporary directory to clone the repository locally, which is
+    deleted upon successful completion of the function.
 
     [1] https://gitlab.gwdg.de/mpsd-cs/spack-environments.git
 
@@ -333,26 +332,42 @@ def get_available_toolchains_upstream(release: str) -> List[str]:
 
     Example
     -------
-    To be added
+    >>> get_available_toolchains('dev-23a')
+    ['foss2021a-cuda-mpi',
+     'foss2021a-mpi',
+     'foss2021a-serial',
+     'foss2022a-cuda-mpi',
+     'foss2022a-mpi',
+     'foss2022a-serial',
+     'global',
+     'global_generic']
 
     """
     logging.debug(f"get_available_toolchains({release=})")
-    print_log = logging.getLogger('print')
-    
+    logging.info(f"Retrieving available toolchains for release {release}")
+    print_log = logging.getLogger("print")
 
-    tmp_dir = tempfile.TemporaryDirectory(prefix='mpsd-software-available-')
-    # tmp_path_name = Path(tempfile.mkdtemp(prefix='mpsd-software-available-'))
+    # create temporary directory
+    tmp_dir = tempfile.TemporaryDirectory(prefix="mpsd-software-available-")
     tmp_dir_path = Path(tmp_dir.name)
+
+    # find toolchains by cloning repository and checking out right branch
     clone_repo(tmp_dir_path, config_vars["spack_environments_repo"], branch=release)
-    toolchains = os.listdir(tmp_dir_path/"toolchains")
+    # look for directories defining the toolchains
+    toolchains = os.listdir(tmp_dir_path / "toolchains")
+
     msg = f"Found toolchains {sorted(toolchains)}"
     logging.debug(msg)
-    print_log.info(f"Release {release}:")
-    for toolchain in toolchains:
+
+    # summarise toolchains found for use
+    print_log.info(f"MPSD software release {release} provides")
+    for toolchain in sorted(toolchains):
         print_log.info("    " + toolchain)
-    tmp_dir.cleanup()
 
+    # remove temporary directory
+    tmp_dir.cleanup()
 
+    return toolchains
 
 
 # Helper class to change directory via context manager
@@ -549,7 +564,9 @@ def record_script_execution_summary(
                 )
 
 
-def clone_repo(target_path: Path, repo_url: str, branch=None) -> None:
+def clone_repo(
+    target_path: Path, repo_url: str, branch=None, capture_output=True
+) -> None:
     """Clone repo locally. Optionally checkout a branch.
 
     Parameters
@@ -560,6 +577,8 @@ def clone_repo(target_path: Path, repo_url: str, branch=None) -> None:
       where to clone the git repository from
     branch: str (defaults to None)
       if provided, checkout this branch after cloning
+    capture_output: bool (defaults to True)
+      capture output, i.e. do not send it to stdout.
     """
     if not target_path.exists():
         target_path.mkdir()
@@ -568,13 +587,16 @@ def clone_repo(target_path: Path, repo_url: str, branch=None) -> None:
         run(
             ["git", "clone", repo_url, str(target_path)],
             check=True,
+            capture_output=capture_output,
         )
     if branch:
         with os_chdir(target_path):
             # Git fetch and checkout the release branch and git pull
             # to be sure that the resulting repo is up to date
-            run(["git", "fetch", "--all"], check=True)
-            checkout_result = run(["git", "checkout", branch])
+            run(["git", "fetch", "--all"], check=True, capture_output=capture_output)
+            checkout_result = run(
+                ["git", "checkout", branch], capture_output=capture_output
+            )
 
             if checkout_result.returncode != 0:
                 msg = f"Couldn't find {branch=}\n"
@@ -591,7 +613,7 @@ def clone_repo(target_path: Path, repo_url: str, branch=None) -> None:
                 logging.error(msg)
                 raise Exception(msg, branches_result)
             else:
-                run(["git", "pull"], check=True)
+                run(["git", "pull"], check=True, capture_output=capture_output)
 
 
 def get_release_info(mpsd_release: str, root_dir: Path) -> Tuple[str, str, List[str]]:
@@ -992,9 +1014,11 @@ def main():
     elif args.action == "prepare":
         prepare_environment(args.release, root_dir)
     elif args.action == "available":
-        get_available_toolchains_upstream(args.release)
+        get_available_toolchains(args.release)
     else:
-        message = f"No known action found ({args.action=}). Should probably never happen."
+        message = (
+            f"No known action found ({args.action=}). Should probably never happen."
+        )
         logging.error(message)
         raise NotImplementedError(message)