Added runner docs

Author: christopolise

docs/API/Runners.md

@@ -0,0 +1,16 @@
+# Runners
+
+## Runners Demo
+::: runners.demo
+
+## Runners Kiosk
+::: runners.kiosk
+
+## Runners Simulator
+::: runners.simulator
+
+## Runners Test
+::: runners.test
+
+## Runners Utils
+::: runners.utils

runners/demo.py

@@ -9,7 +9,14 @@
 
 
 def run(demo_name, simulate, testing):
-    """Main function that runs the demo."""
+    """Main function that runs the demo.
+    
+    Args:
+        demo_name (str): Name of the demo to run.
+        simulate (bool): Whether to simulate the screen or use the physical screen.
+        testing (bool): Whether to run the demo in testing mode.
+    
+    """
 
     if simulate:
         from display.virtual_screen import (  # pylint: disable=import-outside-toplevel
@@ -77,6 +84,14 @@ def run(demo_name, simulate, testing):
 
 
 def _tick(runner, demo, testing):
+    """Run the demo for one tick.
+    
+    Args:
+        runner (generator): Generator that runs the demo.
+        demo (Demo): Demo object.
+        testing (bool): Whether to run the demo in testing mode.
+        
+    """
     if testing:
         before_time = time.time()
 

runners/kiosk.py

@@ -15,6 +15,12 @@ def load_demo(module_name):
     """
     Given a module name it will load the module and get the modules demo
     class.
+    
+    Args:
+        module_name (str): Name of the module to load.
+        
+    Returns:
+        class: The demo class.
     """
     logger.debug(f"Loading {module_name}")
     return utils.get_demo_cls(import_module(module_name))
@@ -24,6 +30,12 @@ def load_demos(demo_dir="demos"):
     """
     Loads all demos for a given directory. It returns the demos in a dictionary
     with the name of the demo as key and the demo module as the value.
+    
+    Args:
+        demo_dir (str): Directory where the demos are located.
+        
+    Returns:
+        dict: Dictionary with the name of the demo as key and the demo module
     """
     logger.debug("Loading demos...")
 
@@ -39,6 +51,9 @@ def get_random_demo(demos):
     """
     Generator that gets a random demo. It makes sure all demos have been
     provided before it repeats a demo, so it's not truly random.
+    
+    Args:
+        demos (dict): Dictionary with the demos.
     """
 
     # Filter out demos that can't be shown without input
@@ -51,7 +66,15 @@ def get_random_demo(demos):
 
 
 def get_demo_from_user(system_queue, demos):
-    """Receives input from user and returns the selected demo."""
+    """Receives input from user and returns the selected demo.
+    
+    Args:
+        system_queue (Queue): Queue to receive input from the user.
+        demos (dict): Dictionary with the demos.
+        
+    Returns:
+        class: The demo class selected by the user.
+    """
 
     try:
         demo_name = system_queue.get(timeout=0.01)
@@ -81,6 +104,13 @@ def play_demo_from_user(
     """
     Plays a demo, monitoring user input. If no input is detected then the demo
     is stopped. If a demo is switched by the user, then this function exits.
+    
+    Args:
+        demo (class): The demo class to play.
+        handle_input (function): Function to handle input.
+        queues (dict): Dictionary with the queues.
+        screen (object): The screen object.
+        user_input_timeout (int): Time to wait for user input.
     """
 
     frame_tick = screen.create_tick(demo.frame_rate)
@@ -113,6 +143,13 @@ def play_demo_from_user(
 def play_demo_from_idle(demo, handle_input, queues, screen, demo_time_override):
     """
     Plays a demo until time expires or data comes into the system queue.
+    
+    Args:
+        demo (class): The demo class to play.
+        handle_input (function): Function to handle input.
+        queues (dict): Dictionary with the queues.
+        screen (object): The screen object.
+        demo_time_override (int): Time to play the demo.
     """
 
     frame_tick = screen.create_tick(demo.frame_rate)
@@ -152,7 +189,14 @@ def play_demo_from_idle(demo, handle_input, queues, screen, demo_time_override):
 
 
 def run_loop(screen, user_input_timeout=300, demo_time_override=None):
-    """Runs the event loop that takes care of input and running the demos."""
+    """Runs the event loop that takes care of input and running the demos.
+    
+    Args:
+        screen (object): The screen object.
+        user_input_timeout (int): Time to wait for user input.
+        demo_time_override (int): Time to play the demo.
+    
+    """
 
     queues = utils.Queues()
 
@@ -208,7 +252,13 @@ def run_loop(screen, user_input_timeout=300, demo_time_override=None):
 
 
 def run(simulate, testing=False):
-    """Runs the kiosk"""
+    """Runs the kiosk
+    
+    Args:
+        simulate (bool): If True, the kiosk will run in simulation mode.
+        testing (bool): If True, the kiosk will run in testing mode.
+        
+    """
 
     if simulate:
         from display.virtual_screen import (  # pylint: disable=import-outside-toplevel

runners/simulator.py

@@ -13,7 +13,16 @@
 
 
 class Simulator:
+    """This is the simulator class that runs the demos."""
+    
     def __init__(self, width, height, demo_dir="demos"):
+        """Constructor
+        
+        Args:
+            width (int): Width of the screen.
+            height (int): Height of the screen.
+            demo_dir (str): Directory where the demos are located.
+        """
         self.width = width
         self.height = height
         self.demo_dir = demo_dir
@@ -55,17 +64,34 @@ def __init__(self, width, height, demo_dir="demos"):
 
     @staticmethod
     def _import_module(module):
+        """Import the module for the first time.
+        
+        Args:
+            module (str): Name of the module to import.
+            
+        Returns:
+            module: The imported module.
+        """
         # First time loading of the demo module
         logger.info(f"Loading {module}")
         return import_module(module)
 
     @staticmethod
     def _reload_module(module):
+        """Reload the module.
+        
+        Args:
+            module (module): The module to reload.
+            
+        Returns:
+            module: The reloaded module.
+        """
         # Hot reload the demo module
         logger.info(f"Reloading {module}")
         return reload(module)
 
     def _reload_demos(self):
+        """Reload all the demos in the demo folder."""
         # Hot load all the demos in the demo folder
         logger.info("Loading demos...")
         demos = utils.get_demos(self.demo_dir)
@@ -81,6 +107,7 @@ def _reload_demos(self):
         self._repopulate_demo_list()
 
     def _repopulate_demo_list(self):
+        """Repopulate the demo list."""
         # if there are more than 13 demos break them up into different pages
         self.demo_lst.clear()
         # create lists to display demos better
@@ -91,6 +118,11 @@ def _repopulate_demo_list(self):
         self.demo_list_index = 0
 
     def _load_game(self, game_name="template"):
+        """Load the game.
+        
+        Args:
+            game_name (str): Name of the game to load.
+        """
         self.lives_text = self.text_font.render(
             "LIVES: " + self.lives_prev, False, (0, 0, 0), (0, 0, 0)
         )
@@ -110,6 +142,7 @@ def _load_game(self, game_name="template"):
         self.screen.clear()
 
     def repopulate(self):
+        """Repopulate the screen."""
         # Hot load demos and populate selection buttons on the screen
         self._reload_demos()
         # for i in range(1, (self.height - 50) // 50):
@@ -169,6 +202,7 @@ def repopulate(self):
             )
 
     def _update_page_count(self):
+        """Update the page count."""
         # update which demo buttons are displayed
         self.demo_list_index += 1
         if self.demo_list_index >= len(self.demo_lst):
@@ -206,6 +240,7 @@ def _update_page_count(self):
             )
 
     def _generate_buttons(self):
+        """Generate the buttons for the screen."""
         self.buttons = [
             Button(
                 # Mandatory Parameters
@@ -271,6 +306,7 @@ def _generate_buttons(self):
         )
 
     def start(self):
+        """Start the main loop."""
         handle_input = controllers.start_inputs(self.system_q, self.input_q)
         tick = self.screen.create_tick(self.game.frame_rate)
 
@@ -325,6 +361,7 @@ def start(self):
 
 
 def run():
+    """Run the simulator."""
     sim = Simulator(25 * 48 + 150, 30 * 24 + 30, "demos")
     sim.start()
 

runners/test.py

@@ -12,6 +12,13 @@ def test_demo(demo_name, demo_module_name):
     """
     Given a demo name and module, it runs the demo for a couple of ticks to
     make sure it doesn't crash.
+    
+    Args:
+        demo_name (str): Name of the demo to test.
+        demo_module_name (str): Name of the module where the demo is located.
+        
+    Returns:
+        bool: Whether the demo passed or not.
     """
     logger.info(f"Testing {demo_name}...")
     display = MagicMock()

runners/utils.py

@@ -17,6 +17,12 @@ def get_demos(demo_dir="demos"):
     Given a directory, it finds all valid demos. It returns a list of tuples
     where the first value is the demo name and the second value is the module
     string of the demo.
+    
+    Args:
+        demo_dir (str): Directory where the demos are located.
+        
+    Returns:
+        list: List of tuples with the demo name and the module string.
     """
     demo_path = Path(demo_dir)
 
@@ -35,6 +41,12 @@ def get_demos(demo_dir="demos"):
 def get_demo_cls(demo_module):
     """
     For a given demo module, it gets the demo class.
+    
+    Args:
+        demo_module (module): Module that contains the demo.
+        
+    Returns:
+        class: The demo class.
     """
     demo_name = demo_module.__name__.rsplit(".", 2)[-2]