Merge branch 'retry-doc-strings' into 'towards-conventional-doc-strings'

Restructure doc strings

See merge request mpsd-cs/mpsd-software-environments!13

mpsd-software-environment.py

@@ -14,6 +14,7 @@ This function builds toolchains for MPSD-HPC at the appropriate directory, \n
 for given system architecture and MPSD software stack version.\n
 The toolchains
 are built using the bash script spack_setup.sh, and the results are logged. """
+
 config_vars = {
     "cmd_log_file": "install.log",
     "build_log_file": (
@@ -28,8 +29,9 @@ config_vars = {
 # Helper class to change directory via context manager
 class os_chdir:
     """
-    The os_chdir class is a context manager that
-    changes the current directory to a specified directory
+    The os_chdir class is a context manager.
+
+    It changes the current directory to a specified directory
     and returns to the original directory after execution.
     """
 
@@ -47,20 +49,26 @@ class os_chdir:
 def setup_log_cmd(
     mpsd_release: str, script_dir: str, msg: str = None, *args, **kwargs
 ) -> None:
-    """The setup_log_cmd function logs the command used to build the
-    toolchains, along with information about the software environment installer
-    branch, the Spack environments branch, and the commit hashes of each. It
-    also logs steps taken in install process using the optional message
-    argument.
-
-    Args:
-        mpsd_release (str): The name of the release to install toolchains for.
-        script_dir (str): The path to the directory where the scripts are located.
-        msg (str, optional): An optional message to log in the command log file.
-
-    Returns:
-        None
+    """
+    Log the command used to build the toolchains.
+
+    It also logs information about the software environment installer branch,
+    the Spack environments branch, and the commit hashes of each.
+    It also logs steps taken
+    in the install process using the optional message argument.
+
+    Parameters
+    ----------
+    - mpsd_release : str
+        The name of the release to install toolchains for.
+    - script_dir : str
+        The path to the directory where the scripts are located.
+    - msg : str, optional
+        An optional message to log in the command log file.
 
+    Returns
+    -------
+    - None
     """
     release_base_dir = script_dir / mpsd_release
 
@@ -125,15 +133,14 @@ def create_dir_structure(mpsd_release: str, script_dir: Path) -> None:
     the specified release and clones the Spack environments repository if it
     doesn't exist.
 
-    Args
-    ----
+    Parameters
+    ----------
     - mpsd_release: A string representing the MPSD release version.
     - script_dir: A Path object representing the path to the scripts directory.
 
     Returns
     -------
     - None
-
     """
     # Create the directory structure for the release
     release_base_dir = script_dir / mpsd_release
@@ -169,28 +176,26 @@ def get_release_info(mpsd_release: str, script_dir: Path) -> Tuple[str, str, Lis
     Get information about the specified release, such as the branch and commit hash
     of the Spack environments repository and the available toolchains.
 
-    Args
-    ----
+    Parameters
+    ----------
     mpsd_release : str
-      the name of the release to get information for.
+        The name of the release to get information for.
     script_dir : pathlib.Path
-      the base directory where releases are stored.
+        The base directory where releases are stored.
 
     Returns
     -------
     spe_branch : str
-      the name of the branch for the Spack environments repository.
+        The name of the branch for the Spack environments repository.
     spe_commit_hash : str
-      the commit hash for the Spack environments repository.
+        The commit hash for the Spack environments repository.
     available_toolchains : list
-      a list of strings representing the available
-      toolchains for the release.
+        A list of strings representing the available toolchains for the release.
 
     Raises
     ------
-    FileNotFoundError :
-      If the release directory does not exist. Run `create_dir_structure()`
-      first.
+    FileNotFoundError
+        If the release directory does not exist. Run `create_dir_structure()` first.
     """
     # Get the info for release
     release_base_dir = script_dir / mpsd_release
@@ -219,21 +224,26 @@ def get_release_info(mpsd_release: str, script_dir: Path) -> Tuple[str, str, Lis
 
 def prepare_environment(mpsd_release: str, script_dir: Path) -> List[str]:
     """
-    Creates
-    - Creates the directory structure for the given MPSD release and clones the
-      spack-environments repository.
-    - Determines the branch and commit hash of the spack-environments repository and
-      the available toolchains.
-    - Logs the command usage.
-
-    Args:
-    - mpsd_release (str): The name of the MPSD release to prepare the environment for.
-    - script_dir (pathlib.Path): The base directory to create the release folder and
-      clone the spack-environments repository into.
-
-    Returns:
-    - available_toolchains (list): A list of available toolchains for the given MPSD
-      release.
+    Create the directory structure for the given MPSD release.
+
+    It does the following steps:
+    Clones the spack-environments repository.
+    Determines the branch and commit hash of the spack-environments repository
+    and the available toolchains.
+    Logs the command usage.
+
+    Parameters
+    ----------
+    mpsd_release : str
+        The name of the MPSD release to prepare the environment for.
+    script_dir : pathlib.Path
+        The base directory to create the release folder and
+        clone the spack-environments repository into.
+
+    Returns
+    -------
+    available_toolchains : list
+        A list of available toolchains for the given MPSD release.
     """
     create_dir_structure(mpsd_release, script_dir)
     spe_branch, spe_commit_hash, available_toolchains = get_release_info(
@@ -252,30 +262,36 @@ def install_environment(
     force_reinstall: bool = False,
     enable_build_cache: bool = False,
 ) -> None:
-    """Installs the specified MPSD release and toolchains to the specified
-    directory using Spack.
-
-    Args:
-        mpsd_release: A string representing the MPSD release version.
-
-        toolchains: A list of strings representing the toolchains to install
-                    (e.g., "foss2021a-mpi", "global_generic", "ALL").
-
-        script_dir: A Path object representing the path to the directory where
-                    the release and toolchains will be installed.
-
-        force_reinstall: A boolean indicating whether to force a reinstallation
-                    even if the release and toolchains already exist. Defaults to False.
+    """
+    Install the specified MPSD release and toolchains.
 
-        enable_build_cache: A boolean indicating whether to build the build
-                    cache when installing toolchains. Defaults to False.
+    The function installs the toolchain to the specified directory, using Spack.
 
-    Raises:
-        ValueError: If a requested toolchain is not available in the specified release.
+    Parameters
+    ----------
+    mpsd_release : str
+        A string representing the MPSD release version.
+    toolchains : list of str
+        A list of strings representing the toolchains to install
+        (e.g., "foss2021a-mpi", "global_generic", "ALL").
+    script_dir : pathlib.Path
+        A Path object representing the path to the directory where
+        the release and toolchains will be installed.
+    force_reinstall : bool, optional
+        A boolean indicating whether to force a reinstallation
+        even if the release and toolchains already exist. Defaults to False.
+    enable_build_cache : bool, optional
+        A boolean indicating whether to build the build cache
+        when installing toolchains. Defaults to False.
 
-    Returns:
-        None
+    Raises
+    ------
+    ValueError
+        If a requested toolchain is not available in the specified release.
 
+    Returns
+    -------
+    None
     """
     print(
         f"Installing release {mpsd_release} with toolchains {toolchains} "