spinx going book

docs/Makefile

@@ -14,6 +14,11 @@ help:
 
 .PHONY: help Makefile
 
+buildapi:
+  sphinx-apidoc.exe -fEM -T -t _templates -o source/source ../marl_factory_grid "../**/marl", "../**/proto"
+  @echo "Auto-generation of 'SOURCEAPI' documentation finished. " \
+          "The generated files were placed in 'source/'"
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

docs/requirements.txt

@@ -1,3 +1,4 @@
 myst_parser
 sphinx-pdj-theme
 sphinx-mdinclude
+sphinx-book-theme

docs/source/code.rst

@@ -1,8 +0,0 @@
-Code
-====
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   code/*

docs/source/conf.py

@@ -15,8 +15,10 @@ release = '2.5.0'
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [#'myst_parser',
+                  'sphinx.ext.todo',
                   'sphinx.ext.autodoc',
-              'sphinx.ext.autosummary',
+                  'sphinx.ext.intersphinx',
+                  # 'sphinx.ext.autosummary',
                   'sphinx.ext.linkcode',
                   'sphinx_mdinclude',
               ]
@@ -24,21 +26,36 @@ extensions = [#'myst_parser',
 templates_path = ['_templates']
 exclude_patterns = ['marl_factory_grid.utils.proto', 'marl_factory_grid.utils.proto.fiksProto_pb2*']
 
+
+autoclass_content = 'both'
+autodoc_class_signature = 'separated'
+autodoc_typehints = 'description'
+autodoc_inherit_docstrings = True
+autodoc_typehints_format = 'short'
+autodoc_default_options = {
+    'members': True,
+    # 'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': True,
+    # 'exclude-members': '__weakref__',
+    'show-inheritance': True,
+}
+autosummary_generate = True
+add_module_names = False
+toc_object_entries = False
+modindex_common_prefix = ['marl_factory_grid.']
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here.
 from pathlib import Path
 import sys
 sys.path.insert(0, (Path(__file__).parents[2]).resolve().as_posix())
 sys.path.insert(0, (Path(__file__).parents[2] / 'marl_factory_grid').resolve().as_posix())
-import sphinx_pdj_theme
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-html_theme = 'alabaster'
+html_theme = "sphinx_book_theme"  # 'alabaster'
-html_theme_path = [sphinx_pdj_theme.get_html_theme_path()]
+# html_static_path = ['_static']
-
-
-html_static_path = ['_static']
 
 # In your configuration, you need to specify a linkcode_resolve function that returns an URL based on the object.
 # https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html
@@ -52,9 +69,4 @@ def linkcode_resolve(domain, info):
     filename = info['module'].replace('.', '/')
     return "https://github.com/illiumst/marl-factory-grid/%s.py" % filename
 
-
-autoclass_content = 'both'
-autosummary_generate = True
-add_module_names = False
-
 print(sys.executable)

docs/source/index.rst

@@ -1,30 +1,20 @@
-.. marl-factory-grid documentation master file, created by
-   sphinx-quickstart on Fri Dec  1 12:55:36 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to marl-factory-grid's documentation!
-=============================================
-
-.. mdinclude:: ../../README.md
-
-Test
-
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
+   :caption: Table of Contents
+   :titlesonly:
 
    installation
    usage
    modifications
-   code
+   source
-
 
 .. note::
    This project is under active development.
 
+.. mdinclude:: ../../README.md
+
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/source/installation.rst

@@ -13,4 +13,10 @@ To use `marl-factory-grid`, first install it using pip:
    (.venv) $ pip install marl-factory-grid
 
 
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
 

docs/source/modifications.rst

@@ -1,5 +1,7 @@
-How to modify the environment or write modules
+Custom Modifications
-==============================================
+====================
+
+This section covers main aspects of working with the environment.
 
 Modifying levels
 ----------------
@@ -68,3 +70,10 @@ PNG-files (transparent background) of square aspect-ratio should do the job, in
    :alt: Wall Image
 .. image:: ../../marl_factory_grid/environment/assets/agent/agent.png
    :alt: Agent Image
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/source.rst

@@ -0,0 +1,17 @@
+Source
+======
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+   :caption: Table of Contents
+   :titlesonly:
+
+   source/*
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/source/marl_factory_grid.environment.entity.rst

@@ -1,53 +1,40 @@
 marl\_factory\_grid.environment.entity package
 ==============================================
 
+.. automodule:: marl_factory_grid.environment.entity
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.environment.entity.agent module
----------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.entity.agent
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.entity.entity module
-----------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.entity.entity
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.entity.object module
-----------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.entity.object
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.entity.util module
---------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.entity.util
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.entity.wall module
---------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.entity.wall
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.environment.entity
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.environment.groups.rst

@@ -1,69 +1,52 @@
 marl\_factory\_grid.environment.groups package
 ==============================================
 
+.. automodule:: marl_factory_grid.environment.groups
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.environment.groups.agents module
-----------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.groups.agents
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.groups.collection module
---------------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.groups.collection
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.groups.global\_entities module
---------------------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.groups.global_entities
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.groups.mixins module
-----------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.groups.mixins
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.groups.objects module
------------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.groups.objects
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.groups.utils module
----------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.groups.utils
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.groups.walls module
----------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.groups.walls
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.environment.groups
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.environment.rst

@@ -1,6 +1,11 @@
 marl\_factory\_grid.environment package
 =======================================
 
+.. automodule:: marl_factory_grid.environment
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Subpackages
 -----------
 
@@ -13,50 +18,32 @@ Subpackages
 Submodules
 ----------
 
-marl\_factory\_grid.environment.actions module
-----------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.actions
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.constants module
-------------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.constants
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.factory module
-----------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.factory
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.rewards module
-----------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.rewards
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.environment.rules module
---------------------------------------------
 
 .. automodule:: marl_factory_grid.environment.rules
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.environment
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.levels.rst

@@ -1,9 +1,6 @@
 marl\_factory\_grid.levels package
 ==================================
 
-Module contents
----------------
-
 .. automodule:: marl_factory_grid.levels
    :members:
    :undoc-members:

docs/source/source/marl_factory_grid.modules.batteries.rst

@@ -1,45 +1,40 @@
 marl\_factory\_grid.modules.batteries package
 =============================================
 
+.. automodule:: marl_factory_grid.modules.batteries
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.modules.batteries.actions module
-----------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.batteries.actions
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.batteries.entitites module
+
-------------------------------------------------------
+.. automodule:: marl_factory_grid.modules.batteries.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 .. automodule:: marl_factory_grid.modules.batteries.entitites
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.batteries.groups module
----------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.batteries.groups
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.batteries.rules module
---------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.batteries.rules
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.modules.batteries
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.modules.clean_up.rst

@@ -1,45 +1,40 @@
 marl\_factory\_grid.modules.clean\_up package
 =============================================
 
+.. automodule:: marl_factory_grid.modules.clean_up
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.modules.clean\_up.actions module
-----------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.clean_up.actions
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.clean\_up.entitites module
+
-------------------------------------------------------
+.. automodule:: marl_factory_grid.modules.clean_up.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 .. automodule:: marl_factory_grid.modules.clean_up.entitites
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.clean\_up.groups module
----------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.clean_up.groups
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.clean\_up.rules module
---------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.clean_up.rules
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.modules.clean_up
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.modules.destinations.rst

@@ -1,45 +1,40 @@
 marl\_factory\_grid.modules.destinations package
 ================================================
 
+.. automodule:: marl_factory_grid.modules.destinations
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.modules.destinations.actions module
--------------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.destinations.actions
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.destinations.entitites module
+
----------------------------------------------------------
+.. automodule:: marl_factory_grid.modules.destinations.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 .. automodule:: marl_factory_grid.modules.destinations.entitites
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.destinations.groups module
-------------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.destinations.groups
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.destinations.rules module
------------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.destinations.rules
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.modules.destinations
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.modules.doors.rst

@@ -1,45 +1,40 @@
 marl\_factory\_grid.modules.doors package
 =========================================
 
+.. automodule:: marl_factory_grid.modules.doors
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.modules.doors.actions module
-------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.doors.actions
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.doors.entitites module
+
---------------------------------------------------
+.. automodule:: marl_factory_grid.modules.doors.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 .. automodule:: marl_factory_grid.modules.doors.entitites
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.doors.groups module
------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.doors.groups
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.doors.rules module
-----------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.doors.rules
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.modules.doors
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.modules.items.rst

@@ -1,45 +1,40 @@
 marl\_factory\_grid.modules.items package
 =========================================
 
+.. automodule:: marl_factory_grid.modules.items
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.modules.items.actions module
-------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.items.actions
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.items.entitites module
+
---------------------------------------------------
+.. automodule:: marl_factory_grid.modules.items.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 .. automodule:: marl_factory_grid.modules.items.entitites
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.items.groups module
------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.items.groups
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.items.rules module
-----------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.items.rules
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.modules.items
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.modules.machines.rst

@@ -1,45 +1,40 @@
 marl\_factory\_grid.modules.machines package
 ============================================
 
+.. automodule:: marl_factory_grid.modules.machines
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.modules.machines.actions module
----------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.machines.actions
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.machines.entitites module
+
------------------------------------------------------
+.. automodule:: marl_factory_grid.modules.machines.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 .. automodule:: marl_factory_grid.modules.machines.entitites
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.machines.groups module
---------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.machines.groups
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.machines.rules module
--------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.machines.rules
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.modules.machines
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.modules.maintenance.rst

@@ -1,37 +1,34 @@
 marl\_factory\_grid.modules.maintenance package
 ===============================================
 
+.. automodule:: marl_factory_grid.modules.maintenance
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.modules.maintenance.entities module
+
--------------------------------------------------------
+.. automodule:: marl_factory_grid.modules.maintenance.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 .. automodule:: marl_factory_grid.modules.maintenance.entities
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.maintenance.groups module
------------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.maintenance.groups
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.maintenance.rules module
-----------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.maintenance.rules
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.modules.maintenance
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.modules.rst

@@ -1,6 +1,11 @@
 marl\_factory\_grid.modules package
 ===================================
 
+.. automodule:: marl_factory_grid.modules
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Subpackages
 -----------
 
@@ -15,11 +20,3 @@ Subpackages
    marl_factory_grid.modules.machines
    marl_factory_grid.modules.maintenance
    marl_factory_grid.modules.zones
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.modules
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.modules.zones.rst

@@ -1,37 +1,34 @@
 marl\_factory\_grid.modules.zones package
 =========================================
 
+.. automodule:: marl_factory_grid.modules.zones
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.modules.zones.entitites module
+
---------------------------------------------------
+.. automodule:: marl_factory_grid.modules.zones.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 .. automodule:: marl_factory_grid.modules.zones.entitites
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.zones.groups module
------------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.zones.groups
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.modules.zones.rules module
-----------------------------------------------
 
 .. automodule:: marl_factory_grid.modules.zones.rules
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.modules.zones
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.rst

@@ -1,12 +1,18 @@
 marl\_factory\_grid package
 ===========================
 
+.. automodule:: marl_factory_grid
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Subpackages
 -----------
 
 .. toctree::
    :maxdepth: 4
 
+   marl_factory_grid.algorithms
    marl_factory_grid.environment
    marl_factory_grid.levels
    marl_factory_grid.modules
@@ -15,18 +21,8 @@ Subpackages
 Submodules
 ----------
 
-marl\_factory\_grid.quickstart module
--------------------------------------
 
 .. automodule:: marl_factory_grid.quickstart
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.utils.logging.rst

@@ -1,29 +1,22 @@
 marl\_factory\_grid.utils.logging package
 =========================================
 
+.. automodule:: marl_factory_grid.utils.logging
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.utils.logging.envmonitor module
----------------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.logging.envmonitor
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.logging.recorder module
--------------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.logging.recorder
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.utils.logging
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.utils.plotting.rst

@@ -1,37 +1,28 @@
 marl\_factory\_grid.utils.plotting package
 ==========================================
 
+.. automodule:: marl_factory_grid.utils.plotting
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Submodules
 ----------
 
-marl\_factory\_grid.utils.plotting.plot\_compare\_runs module
--------------------------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.plotting.plot_compare_runs
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.plotting.plot\_single\_runs module
-------------------------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.plotting.plot_single_runs
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.plotting.plotting\_utils module
----------------------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.plotting.plotting_utils
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.utils.plotting
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/source/marl_factory_grid.utils.rst

@@ -1,6 +1,11 @@
 marl\_factory\_grid.utils package
 =================================
 
+.. automodule:: marl_factory_grid.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Subpackages
 -----------
 
@@ -13,90 +18,62 @@ Subpackages
 Submodules
 ----------
 
-marl\_factory\_grid.utils.config\_parser module
------------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.config_parser
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.helpers module
-----------------------------------------
 
 .. automodule:: marl_factory_grid.utils.helpers
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.level\_parser module
-----------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.level_parser
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.observation\_builder module
------------------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.observation_builder
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.ray\_caster module
---------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.ray_caster
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.renderer module
------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.renderer
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.results module
-----------------------------------------
 
 .. automodule:: marl_factory_grid.utils.results
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.states module
----------------------------------------
 
 .. automodule:: marl_factory_grid.utils.states
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.tools module
---------------------------------------
 
 .. automodule:: marl_factory_grid.utils.tools
    :members:
    :undoc-members:
    :show-inheritance:
 
-marl\_factory\_grid.utils.utility\_classes module
--------------------------------------------------
 
 .. automodule:: marl_factory_grid.utils.utility_classes
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: marl_factory_grid.utils
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/usage.rst

@@ -1,5 +1,5 @@
-Using the environment with your agents
+Basic Usage
-======================================
+===========
 
 Environment objects, including agents, entities and rules, that are specified in a *yaml*-configfile will be loaded automatically.
 Using ``quickstart_use`` creates a default config-file and another one that lists all possible options of the environment.
@@ -63,3 +63,11 @@ Evaluating the run
 If monitoring and recording are enabled, the environment states will be traced and recorded automatically.
 
 Plotting. At the moment a plot of the evaluation score across the different episodes is automatically generated.
+
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

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

@@ -24,8 +24,8 @@ class FactoryConfigParser(object):
          This class parses the factory env config file.
 
 
-        :param config_path: Test
+        :param config_path: Path to where the 'config.yml' is.
-        :param custom_modules_path: Test
+        :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)