fix styling and add in cross-references to portions of Merlin codebase

merlin/display.py

@@ -86,6 +86,9 @@ class ConnProcess(Process):
         _pconn: The parent connection for inter-process communication.
         _cconn: The child connection for inter-process communication.
         exception: Stores the exception raised during the process run.
+
+    Methods:
+        run: Executes the process's main logic.
     """
 
     def __init__(self, *args, **kwargs):
@@ -322,10 +325,11 @@ def display_status_task_by_task(status_obj: "DetailedStatus", test_mode: bool =
     unless the prompts are disabled through the no-prompts flag.
 
     Args:
-        status_obj: An instance of DetailedStatus containing information
-                    about the current state of tasks.
-        test_mode: If True, runs the function in testing mode, suppressing output
-                    and reducing the task limit for prompts. Defaults to False.
+        status_obj (study.status.DetailedStatus): An instance of
+            [`DetailedStatus`][study.status.DetailedStatus] containing information about
+            the current state of tasks.
+        test_mode: If True, runs the function in testing mode, suppressing output and
+            reducing the task limit for prompts. Defaults to False.
     """
     args = status_obj.args
     try:
@@ -387,12 +391,11 @@ def _display_summary(state_info: Dict[str, str], cb_help: bool):
     symbols if specified.
 
     Args:
-        state_info: A dictionary containing information related 
-                    to task states for a step. Each entry should 
-                    correspond to a specific task state with its 
-                    associated properties (e.g., count, total, name).
-        cb_help: If True, provides colorblind assistance by using symbols 
-                in the display. Defaults to False for standard output.
+        state_info: A dictionary containing information related to task states
+            for a step. Each entry should correspond to a specific task state
+            with its associated properties (e.g., count, total, name).
+        cb_help: If True, provides colorblind assistance by using symbols in the
+            display. Defaults to False for standard output.
     """
     # Build a summary list of task info
     print("\nSUMMARY:")
@@ -439,12 +442,12 @@ def display_status_summary(  # pylint: disable=R0912
     it suppresses output and returns a dictionary of state information instead.
 
     Args:
-        status_obj: An instance of Status containing information about task states
-                    and associated data for the study.
+        status_obj (study.status.Status): An instance of [`Status`][study.status.Status] containing
+            information about task states and associated data for the study.
         non_workspace_keys: A set of keys in requested_statuses that are not workspace keys. 
-                            Typically includes keys like "parameters", "task_queue", and "workers".
+            Typically includes keys like "parameters", "task_queue", and "workers".
         test_mode: If True, runs in test mode; suppresses printing and returns a dictionary 
-                    of state information for each step. Defaults to False.
+            of state information for each step. Defaults to False.
 
     Returns:
         An empty dictionary in regular mode. In test mode, returns a dictionary containing 
@@ -552,9 +555,8 @@ def display_progress_bar(  # pylint: disable=R0913,R0914
     Args:
         current: Current progress value.
         total: Total value representing 100% completion.
-        state_info: Dictionary containing state information about tasks.
-                    This can override color settings and modifies 
-                    how the progress bar is displayed.
+        state_info: Dictionary containing state information about tasks. This can override
+            color settings and modifies how the progress bar is displayed.
         prefix: Optional prefix string to display before the progress bar.
         suffix: Optional suffix string to display after the progress bar.
         decimals: Number of decimal places to display in the percentage (default is 1).

merlin/main.py

@@ -69,12 +69,17 @@
 
 
 class HelpParser(ArgumentParser):
-    """This class overrides the error message of the argument parser to
-    print the help message when an error happens."""
+    """
+    This class overrides the error message of the argument parser to
+    print the help message when an error happens.
+
+    Methods:
+        error: Override the error message of the `ArgumentParser` class.
+    """
 
     def error(self, message: str):
         """
-        Override the error message of the ArgumentParser class.
+        Override the error message of the `ArgumentParser` class.
 
         Args:
             message: The error message to log.
@@ -143,20 +148,23 @@ def parse_override_vars(
 
 def get_merlin_spec_with_override(args: Namespace) -> Tuple[MerlinSpec, str]:
     """
-    Shared command to retrieve a `MerlinSpec` object and an expanded filepath.
+    Shared command to retrieve a [`MerlinSpec`][spec.specification.MerlinSpec] object
+    and an expanded filepath.
 
     This function processes parsed command-line interface (CLI) arguments to validate 
     and expand the specified filepath and any associated variables. It then constructs 
-    and returns a `MerlinSpec` object based on the provided specification. 
+    and returns a [`MerlinSpec`][spec.specification.MerlinSpec] object based on the
+    provided specification.
 
     Args:
         args: Parsed CLI arguments containing:\n
             - `specification`: the path to the specification file
             - `variables`: optional variable overrides to customize the spec.
 
     Returns:
-        spec: An instance of the `MerlinSpec` class with the 
-              expanded configuration based on the provided filepath and variables.
+        spec (spec.specification.MerlinSpec): An instance of the
+            [`MerlinSpec`][spec.specification.MerlinSpec] class with the expanded
+            configuration based on the provided filepath and variables.
         filepath: The expanded filepath derived from the specification.
     """
     filepath = verify_filepath(args.specification)
@@ -301,22 +309,23 @@ def query_status(args: Namespace):
     CLI command for querying the status of studies.
 
     This function processes the given command-line arguments to determine the 
-    status of a study. It constructs either a `Status` object or a `DetailedStatus` 
-    object based on the specified command and the arguments provided. The function 
-    handles validations for the task server input and the output format specified 
-    for status dumping.
+    status of a study. It constructs either a [`Status`][study.status.Status] object
+    or a [`DetailedStatus`][study.status.DetailedStatus] object based on the specified
+    command and the arguments provided. The function handles validations for the task
+    server input and the output format specified for status dumping.
 
     Object mapping:
-        - `merlin status` -> `Status` object
-        - `merlin detailed-status` -> `DetailedStatus` object
+        - `merlin status` -> [`Status`][study.status.Status] object
+        - `merlin detailed-status` -> [`DetailedStatus`][study.status.DetailedStatus]
+        object
 
     Args:
         args: Parsed CLI arguments containing user inputs for the status query.
 
     Raises:
         ValueError: 
-            If the task server specified is not supported (only "celery" is valid).
-            If the --dump filename provided does not end with ".csv" or ".json".
+            - If the task server specified is not supported (only "celery" is valid).
+            - If the --dump filename provided does not end with ".csv" or ".json".
     """
     print(banner_small)
 
@@ -374,10 +383,10 @@ def query_queues(args: Namespace):
 
     Raises:
         ValueError: 
-            If a specification is not provided when steps are specified and the 
+            - If a specification is not provided when steps are specified and the 
             steps do not include "all".
-            If variables are included without a corresponding specification.
-            If the specified dump filename does not end with '.json' or '.csv'.
+            - If variables are included without a corresponding specification.
+            - If the specified dump filename does not end with '.json' or '.csv'.
     """
     print(banner_small)
 
@@ -491,7 +500,7 @@ def print_info(args: Namespace):
     display.print_info(args)
 
 
-def config_merlin(args: Namespace) -> None:
+def config_merlin(args: Namespace):
     """
     CLI command to set up the default Merlin configuration.
 
@@ -970,8 +979,8 @@ def generate_worker_touching_parsers(subparsers: ArgumentParser) -> None:
     specification.
 
     Args:
-        subparsers: An instance of ArgumentParser for adding command-line subcommands related 
-            to worker management.
+        subparsers: An instance of ArgumentParser for adding command-line subcommands
+            related to worker management.
     """
     # merlin run-workers
     run_workers: ArgumentParser = subparsers.add_parser(