spinx going book

marl_factory_grid/__init__.py

@@ -1 +1,7 @@
 from .quickstart import init
+from environment.factory import Factory
+"""
+Main module of the 'marl-factory-grid'-environment.
+Configure the :class:.Factory with any 'conf.yaml' file.
+Examples can be found in :module:.levels .
+"""

marl_factory_grid/algorithms/static/utils.py

@@ -8,10 +8,10 @@ def points_to_graph(coordiniates, allow_euclidean_connections=True, allow_manhat
     """
     Given a set of coordinates, this function contructs a non-directed graph, by conncting adjected points.
     There are three combinations of settings:
-        Allow all neigbors:     Distance(a, b) <= sqrt(2)
-        Allow only manhattan:   Distance(a, b) == 1
-        Allow only Euclidean:   Distance(a, b) == sqrt(2)
 
+    - Allow all neigbors:     Distance(a, b) <= sqrt(2)
+    - Allow only manhattan:   Distance(a, b) == 1
+    - Allow only Euclidean:   Distance(a, b) == sqrt(2)
 
     :param coordiniates: A set of coordinates.
     :type coordiniates: Tuple[int, int]

marl_factory_grid/environment/actions.py

@@ -10,7 +10,6 @@ from marl_factory_grid.utils.results import ActionResult
 TYPE_COLLISION = 'collision'
 
 class Action(abc.ABC):
-
     @property
     def name(self):
         return self._identifier
@@ -18,12 +17,28 @@ class Action(abc.ABC):
     @abc.abstractmethod
     def __init__(self, identifier: str, default_valid_reward: float,  default_fail_reward: float,
                  valid_reward: float | None = None, fail_reward: float | None = None):
+        """
+        Todo
+
+        :param identifier:
+        :param default_valid_reward:
+        :param default_fail_reward:
+        :param valid_reward:
+        :param fail_reward:
+        """
         self.fail_reward = fail_reward if fail_reward is not None else default_fail_reward
         self.valid_reward = valid_reward if valid_reward is not None else default_valid_reward
         self._identifier = identifier
 
     @abc.abstractmethod
     def do(self, entity, state) -> Union[None, ActionResult]:
+        """
+        Let the :class:`marl_factory_grid.environment.entity.entity.Entity` perform the given.
+
+        :param entity: The entity to perform the action; mostly `marl_factory_grid.environment.entity.agent.Agent`
+        :param state: The current :class:'marl_factory_grid.utils.states.Gamestate'
+        :return:
+        """
         validity = bool(random.choice([0, 1]))
         return self.get_result(validity, entity)
 

marl_factory_grid/levels/__init__.py

@@ -0,0 +1,16 @@
+"""
+
+The place to put the level-files.
+Per default the following levels are provided:
+
+- eight_puzzle
+- large
+- large_qquad
+- narrow_corridor
+- rooms
+- shelves
+- simple
+- two_rooms
+
+
+"""

marl_factory_grid/modules/__init__.py

@@ -5,3 +5,11 @@ from .doors import *
 from .items import *
 from .machines import *
 from .maintenance import *
+
+"""
+modules
+=======
+
+Todo
+
+"""

marl_factory_grid/modules/items/__init__.py

@@ -1,3 +1,11 @@
 from .actions import ItemAction
 from .entitites import Item, DropOffLocation
 from .groups import DropOffLocations, Items, Inventory, Inventories
+
+"""
+items
+=====
+
+Todo
+
+"""

marl_factory_grid/modules/machines/__init__.py

@@ -1,2 +1,10 @@
 from .entitites import Machine
 from .groups import Machines
+
+"""
+machines
+========
+
+Todo
+
+"""

marl_factory_grid/modules/maintenance/__init__.py

@@ -1,2 +1,9 @@
 from .entities import Maintainer
 from .groups import Maintainers
+"""
+maintenance
+===========
+
+Todo
+
+"""

marl_factory_grid/utils/__init__.py

@@ -1,3 +1,11 @@
 from . import helpers as h
 from . import helpers
 from .results import Result, DoneResult, ActionResult, TickResult
+
+"""
+Utils
+=====
+
+Todo
+
+"""

marl_factory_grid/utils/config_parser.py

@@ -21,11 +21,11 @@ class FactoryConfigParser(object):
 
     def __init__(self, config_path, custom_modules_path: Union[PathLike] = None):
         """
-        This class parses the factory env config file.
+         This class parses the factory env config file.
 
 
-        :param config_path: Test
-        :param custom_modules_path: Test
+        :param config_path: Path to where the 'config.yml' is.
+        :param custom_modules_path: Additional search path for custom modules, levels, entities, etc..
         """
         self.config_path = Path(config_path)
         self.custom_modules_path = Path(custom_modules_path) if custom_modules_path is not None else custom_modules_path

marl_factory_grid/utils/logging/__init__.py

@@ -0,0 +1,7 @@
+"""
+logging
+=======
+
+Todo
+
+"""

marl_factory_grid/utils/logging/recorder.py

@@ -11,6 +11,13 @@ class EnvRecorder(Wrapper):
 
     def __init__(self, env, filepath: Union[str, PathLike] = None,
                  episodes: Union[List[int], None] = None):
+        """
+
+        Todo
+
+        :param env:
+        :param filepath:
+        """
         super(EnvRecorder, self).__init__(env)
         self.filepath = filepath
         self.episodes = episodes

marl_factory_grid/utils/observation_builder.py

@@ -31,6 +31,9 @@ class OBSBuilder(object):
 
     def __init__(self, level_shape: np.size, state: Gamestate, pomdp_r: int):
         """
+        OBSBuilder
+        ==========
+
         TODO
 
 

marl_factory_grid/utils/plotting/__init__.py

@@ -0,0 +1,7 @@
+"""
+PLotting
+========
+
+Todo
+
+"""

marl_factory_grid/utils/plotting/plot_compare_runs.py

@@ -13,6 +13,14 @@ MODEL_MAP = None
 
 
 def compare_seed_runs(run_path: Union[str, PathLike], use_tex: bool = False):
+    """
+
+    Todo
+
+    :param filepath:
+    :param ext:
+    :return:
+    """
     run_path = Path(run_path)
     df_list = list()
     for run, monitor_file in enumerate(run_path.rglob('monitor*.pick')):
@@ -49,6 +57,14 @@ def compare_seed_runs(run_path: Union[str, PathLike], use_tex: bool = False):
 
 def compare_model_runs(run_path: Path, run_identifier: Union[str, int], parameter: Union[str, List[str]],
                        use_tex: bool = False):
+    """
+
+    Todo
+
+    :param filepath:
+    :param ext:
+    :return:
+    """
     run_path = Path(run_path)
     df_list = list()
     parameter = [parameter] if isinstance(parameter, str) else parameter
@@ -89,6 +105,14 @@ def compare_model_runs(run_path: Path, run_identifier: Union[str, int], paramete
 
 def compare_all_parameter_runs(run_root_path: Path, parameter: Union[str, List[str]],
                                param_names: Union[List[str], None] = None, str_to_ignore='', use_tex: bool = False):
+    """
+
+    Todo
+
+    :param filepath:
+    :param ext:
+    :return:
+    """
     run_root_path = Path(run_root_path)
     df_list = list()
     parameter = [parameter] if isinstance(parameter, str) else parameter

marl_factory_grid/utils/plotting/plot_single_runs.py

@@ -11,6 +11,14 @@ from marl_factory_grid.utils.plotting.plotting_utils import prepare_plot
 
 def plot_single_run(run_path: Union[str, PathLike], use_tex: bool = False, column_keys=None,
                     file_key: str ='monitor', file_ext: str ='pkl'):
+    """
+
+    Todo
+
+    :param filepath:
+    :param ext:
+    :return:
+    """
     run_path = Path(run_path)
     df_list = list()
     if run_path.is_dir():

marl_factory_grid/utils/plotting/plotting_utils.py

@@ -1,7 +1,6 @@
 import seaborn as sns
 import matplotlib as mpl
 from matplotlib import pyplot as plt
-
 PALETTE = 10 * (
     "#377eb8",
     "#4daf4a",
@@ -20,6 +19,14 @@ PALETTE = 10 * (
 
 
 def plot(filepath, ext='png'):
+    """
+
+    Todo
+
+    :param filepath:
+    :param ext:
+    :return:
+    """
     plt.tight_layout()
     figure = plt.gcf()
     ax = plt.gca()
@@ -35,6 +42,13 @@ def plot(filepath, ext='png'):
 
 
 def prepare_tex(df, hue, style, hue_order):
+    """
+    Todo
+
+    :param filepath:
+    :param ext:
+    :return:
+    """
     sns.set(rc={'text.usetex': True}, style='whitegrid')
     lineplot = sns.lineplot(data=df, x='Episode', y='Score', ci=95, palette=PALETTE,
                             hue_order=hue_order, hue=hue, style=style)
@@ -45,6 +59,13 @@ def prepare_tex(df, hue, style, hue_order):
 
 
 def prepare_plt(df, hue, style, hue_order):
+    """
+    Todo
+
+    :param filepath:
+    :param ext:
+    :return:
+    """
     print('Struggling to plot Figure using LaTeX - going back to normal.')
     plt.close('all')
     sns.set(rc={'text.usetex': False}, style='whitegrid')
@@ -57,6 +78,13 @@ def prepare_plt(df, hue, style, hue_order):
 
 
 def prepare_center_double_column_legend(df, hue, style, hue_order):
+    """
+    Todo
+
+    :param filepath:
+    :param ext:
+    :return:
+    """
     print('Struggling to plot Figure using LaTeX - going back to normal.')
     plt.close('all')
     sns.set(rc={'text.usetex': False}, style='whitegrid')
@@ -70,6 +98,13 @@ def prepare_center_double_column_legend(df, hue, style, hue_order):
 
 
 def prepare_plot(filepath, results_df, ext='png', hue='Measurement', style=None, use_tex=False):
+    """
+    Todo
+
+    :param filepath:
+    :param ext:
+    :return:
+    """
     df = results_df.copy()
     df[hue] = df[hue].str.replace('_', '-')
     hue_order = sorted(list(df[hue].unique()))

marl_factory_grid/utils/utility_classes.py

@@ -6,7 +6,10 @@ import numpy as np
 
 
 class MarlFrameStack(gym.ObservationWrapper):
-    """todo @romue404"""
+    """
+
+    todo @romue404
+    """
     def __init__(self, env):
         super().__init__(env)