Merge branch 'review-documentation' into 'main'

Review documentation

See merge request mpsd-cs/mpsd-software!63

mpsd-software.py

@@ -27,11 +27,19 @@ else:
 
 
 about_intro = f"""
-Build toolchains using Spack.\n
+Build software as on MPSD HPC.
 
-This function builds toolchains for MPSD-HPC at the appropriate directory,
-for given system architecture and MPSD software stack version. The toolchains
-are built using the bash script spack_setup.sh, and the results are logged.
+
+    This tool builds software package sets (including toolchains for Octopus).
+    It follows recipes as used on the MPSD HPC system and the (spack-based)
+    Octopus buildbot. Compiled software is organised into MPSD software release
+    versions (such as `dev-23a`) and CPU microarchitecture (such as `sandybridge`).
+    
+    Compiled packages and toolchains can be activated and used via `module load` as
+    on the HPC system.
+    
+    Further documentation is available in the README.rst file, online at
+    https://gitlab.gwdg.de/mpsd-cs/mpsd-software/-/blob/main/README.rst
 
 Command line usage:
 
@@ -45,23 +53,24 @@ about_epilog = f"""
 
 Examples:
 
-1. Query what package sets and toolchains are available in relase dev-23a
-
-   $> {sys.argv[0]} available dev-23a
-
-2. Install foss2022a-serial toolchain
-
-   $> {sys.argv[0]} install dev-23a foss2022a-serial
-
-3. Check what package sets and toolchains are installed from release dev-23a
-
-   $> {sys.argv[0]} status dev-23a
-
-Documentation: https://gitlab.gwdg.de/mpsd-cs/mpsd-software/-/blob/main/README.rst
+    1. Query what package sets and toolchains are available for installation in
+       release dev-23a
+    
+       $> {sys.argv[0]} available dev-23a
+    
+    2. Install foss2022a-serial toolchain from the dev-23a release
+    
+       $> {sys.argv[0]} install dev-23a foss2022a-serial
+    
+    3. Check what package sets and toolchains are installed from release dev-23a
+    
+       $> {sys.argv[0]} status dev-23a
+    
+       The `status` command also displays the `module use` command needed to load
+       the created modules.
 
 """
 
-
 call_date_iso = (
     datetime.datetime.now().replace(microsecond=0).isoformat().replace(":", "-")
 )
@@ -1066,7 +1075,6 @@ def main():
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     parser.add_argument(
-        "--log",
         "-l",
         dest="loglevel",
         choices=["warning", "info", "debug"],
@@ -1082,7 +1090,7 @@ def main():
     )
     subparsers.required = True
     list_of_cmds = [
-        ("available", "Show software available for installation"),
+        ("available", "What is available for installation?"),
         ("install", "Install a software environment"),
         # ("reinstall", "Reinstall a software environment"),
         # ("remove", "Remove a software environment or toolchains from an environment"),
@@ -1117,18 +1125,18 @@ def main():
             )
             if cmd in ["install", "reinstall", "remove"]:
                 # "install" command needs additional documentation
-                tool_chain_help = (
-                    f"One or more toolchains to command {cmd}. "
-                    "Use 'ALL' to refer to all available toolchains."
+                package_set_help = (
+                    f"One or more package sets (like toolchains) to be {cmd}ed. "
+                    "Use 'ALL' to refer to all available package sets."
                 )
 
                 subp.add_argument(
-                    "toolchain",  # first option defines attribute
-                    # name `args.toolchain` in `args = parser_args()`
+                    "package_set",  # first option defines attribute
+                    # name `args.package_set` in `args = parser_args()`
                     type=str,
                     nargs="+",
                     default="NONE",
-                    help=tool_chain_help,
+                    help=package_set_help,
                 )
                 subp.add_argument(
                     "--enable-build-cache",
@@ -1159,12 +1167,12 @@ def main():
 
     # Check the command and run related function
     if args.action == "remove":
-        remove_environment(args.release, args.toolchain, root_dir)
+        remove_environment(args.release, args.package_set, root_dir)
     elif args.action == "start-new":
         start_new_environment(args.from_release, args.to_release, root_dir)
     elif args.action == "install":
         install_environment(
-            args.release, args.toolchain, root_dir, args.enable_build_cache
+            args.release, args.package_set, root_dir, args.enable_build_cache
         )
     elif args.action == "status":
         _ = environment_status(args.release, root_dir)