major documentation writing

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "malcolm-test"
-version = "0.5.1"
+version = "0.6.0"
 authors = [
   { name="Seth Grover", email="[email protected]" },
 ]

src/maltest/__init__.py

@@ -1,3 +1,14 @@
+"""
+malcolm-test serves to run an instance of Malcolm (https://idaholab.github.io/Malcolm/)
+and verify the results of system tests executed against it.
+
+This package contains the following modules:
+- maltest: contains the CLI interface and high-level execution logic
+- utils: contains classes used for managing and interfacing with Malcolm VM
+"""
+
+# -*- coding: utf-8 -*-
+
 from importlib.metadata import version, PackageNotFoundError
 from maltest.utils import MALTEST_PROJECT_NAME
 

src/maltest/maltest.py

@@ -1,3 +1,7 @@
+"""
+malcolm-test module containing the CLI interface and high-level execution logic
+"""
+
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
@@ -24,20 +28,35 @@
     ShuttingDown,
 )
 
-###################################################################################################
 script_name = os.path.basename(__file__)
 script_path = os.path.dirname(os.path.realpath(__file__))
 
 
-###################################################################################################
-# handle sigint/sigterm and set a global shutdown variable
 def shutdown_handler(signum, frame):
+    """
+    shutdown_handler: Signal handler for interrupting program execution with SIGKILL or SIGINT,
+    setting ShuttingDown to True
+
+    Args:
+        signum - The signal number (e.g., signal.SIGINT for Ctrl-C)
+        frame - The current stack frame
+
+    Returns:
+        None
+    """
     ShuttingDown[0] = True
 
 
-###################################################################################################
-# main
 def main():
+    """
+    main: Main program execution
+
+    Args:
+        None (see --help for command-line arguments)
+
+    Returns:
+        0 for success, non-0 for error
+    """
     global ShuttingDown
 
     parser = argparse.ArgumentParser(
@@ -76,7 +95,7 @@ def main():
         dest='repoUrl',
         metavar='<string>',
         type=str,
-        default=os.getenv('MALCOLM_REPO_URL', 'idaholab'),
+        default=os.getenv('MALCOLM_REPO_URL', 'https://github.com/idaholab/Malcolm'),
         help='Malcolm repository url (e.g., https://github.com/idaholab/Malcolm)',
     )
     repoArgGroup.add_argument(
@@ -228,7 +247,7 @@ def main():
         default=True,
         help=f'Start Malcolm once provisioning is complete (default true)',
     )
-    parser.add_argument(
+    configArgGroup.add_argument(
         '-r',
         '--rm',
         dest='removeAfterExec',
@@ -409,7 +428,6 @@ def main():
     return exitCode
 
 
-###################################################################################################
 if __name__ == '__main__':
     if main() > 0:
         sys.exit(0)

src/maltest/tests/conftest.py

@@ -1,6 +1,13 @@
+"""
+provides fixtures usable by all pytests in the system
+
+See https://docs.pytest.org/en/stable/reference/fixtures.html#conftest-py-sharing-fixtures-across-multiple-files
+"""
+
 # -*- coding: utf-8 -*-
 
 import pytest
+
 from maltest.utils import (
     get_malcolm_vm_info,
     get_pcap_hash_map,
@@ -12,24 +19,54 @@
 
 @pytest.fixture
 def malcolm_vm_info():
+    """
+    malcolm_vm_info: fixture wrapping .utils.get_malcolm_vm_info
+
+    Returns:
+        see .utils.get_malcolm_vm_info
+    """
     yield get_malcolm_vm_info()
 
 
 @pytest.fixture
 def pcap_hash_map():
+    """
+    pcap_hash_map: fixture wrapping .utils.get_pcap_hash_map
+
+    Returns:
+        see .utils.get_pcap_hash_map
+    """
     yield get_pcap_hash_map()
 
 
 @pytest.fixture
 def malcolm_http_auth():
+    """
+    malcolm_http_auth: fixture wrapping .utils.get_malcolm_http_auth
+
+    Returns:
+        see .utils.get_malcolm_http_auth
+    """
     yield get_malcolm_http_auth()
 
 
 @pytest.fixture
 def database_objs():
+    """
+    database_objs: fixture wrapping .utils.get_database_objs
+
+    Returns:
+        see .utils.get_database_objs
+    """
     yield get_database_objs()
 
 
 @pytest.fixture
 def malcolm_url():
+    """
+    malcolm_url: fixture wrapping .utils.get_malcolm_url
+
+    Returns:
+        see .utils.get_malcolm_url
+    """
     yield get_malcolm_url()

src/maltest/utils.py

@@ -1,3 +1,12 @@
+"""
+malcolm-test module containing classes used for managing and interfacing with a Malcolm VM
+
+The classes of interest in this module include:
+
+- MalcolmTestCollection - A pytest plugin used to gather the list of tests to be run
+- MalcolmVM - Represents a Malcolm instance running inside a virter-managed libvirt virtual machine
+"""
+
 # -*- coding: utf-8 -*-
 
 import ast
@@ -325,7 +334,6 @@ def __init__(self, username=None, password=None):
             self.DatabaseInitArgs['basic_auth'] = (username, password)
 
 
-###################################################################################################
 class MalcolmTestCollection(object):
     """
     MalcolmTestCollection: A pytest plugin (https://docs.pytest.org/en/stable/how-to/writing_plugins.html)