docs: update docstrings for pdoc generation (#18)

* docs: update explorer docstr

* docs: update map docstrs

* docs: update system docstrs

* docs: add wrapper docstr

* docs: add callback docstr

* docs: update callback readme with right path

* docs: update callbacks docstring

services/base/AutoDiscServer/libs/auto_disc/auto_disc/__init__.py

@@ -0,0 +1 @@
+"""Core modules of the software are located under this module namespace."""

services/base/AutoDiscServer/libs/auto_disc/auto_disc/explorers/IMGEPExplorer.py

@@ -1,3 +1,5 @@
+"""The simplest possible algorithm of Intrinsically Motivated Goal Exploration Processes
+"""
 from functools import partial
 from typing import Any, Dict, List
 
@@ -32,8 +34,7 @@
 )
 @DictConfigParameter("mutator_config", default={})
 class IMGEPFactory:
-    """
-    Factory class providing interface with config parameters and therefore the
+    """Factory class providing interface with config parameters and therefore the
     frontend
     """
 
@@ -131,7 +132,7 @@ def __init__(
         self._history_saver = SaveWrapper()
 
     def bootstrap(self) -> Dict:
-        """Returns an initial sample needed to bootstrap the exploration loop."""
+        """Return an initial sample needed to bootstrap the exploration loop."""
         data_dict = {}
         # initialize sample
         params_init = self.parameter_map.sample()
@@ -146,16 +147,16 @@ def bootstrap(self) -> Dict:
         return data_dict
 
     def map(self, system_output: Dict) -> Dict:
-        """Maps the raw output of the system rollout to a subsequent parameter
+        """Map the raw output of the system rollout to a subsequent parameter
         configuration to try.
 
-        #### Args:
-            system_output: A dictionary where the key `self.premap_key` indexes
-                the raw output given at the end of the previous system rollout.
+        Args:
+            system_output:
+                A dictionary where the key `self.premap_key` indexes the raw
+                output given at the end of the previous system rollout.
 
-        #### Returns:
-            A dictionary where the key `self.postmap_key` indexes the
-            parameters to try in the next trial.
+        Returns:
+            A dictionary where the key `self.postmap_key` indexes the parameters to try in the next trial.
         """
         # either do nothing, or update dict by changing "output" -> "raw_output"
         # and adding new "output" key which is the result of the behavior map
@@ -197,15 +198,15 @@ def suggest_trial(self, lookback_length: int = -1) -> torch.Tensor:
         """Sample according to the policy a new trial of parameters for the
         system.
 
-        #### Args:
-            lookback_length: number of previous trials to consider when choosing
-                the next trial, i.e., it is a batch size based on the save
-                frequency.
+        Args:
+            lookback_length:
+                number of previous trials to consider when choosing the next
+                trial, i.e., it is a batch size based on the save frequency.
 
                 Note that the default `lookback_length = -1` will retrieve the
                 entire  history.
 
-        #### Returns:
+        Returns:
             A `torch.Tensor` containing the parameters to try.
         """
         goal = self.behavior_map.sample()
@@ -220,10 +221,10 @@ def observe_results(self, system_output: Dict) -> Dict:
         """Read the raw output observed and process it into a discovered
         behavior.
 
-        #### Args:
+        Args:
             system_output: See arguments for `.map`.
 
-        #### Returns:
+        Returns:
             A dictionary of the observed behavior/feature vector associated with
             the raw `system_output`
         """

services/base/AutoDiscServer/libs/auto_disc/auto_disc/explorers/__init__.py

@@ -1 +1,4 @@
+"""An `Explorer` encapsulates and abstracts the algorithmic loop which is run to
+conduct automatic exploration of the system.
+"""
 from .IMGEPExplorer import IMGEPExplorer, IMGEPFactory

services/base/AutoDiscServer/libs/auto_disc/auto_disc/maps/Map.py

@@ -13,24 +13,24 @@ class Map(Leaf, metaclass=ABCMeta):
     input-output relation) that is also stateful. It takes a payload of data as
     input and returns an new payload of data as output, without mutating
     the input.
+
+    Attributes:
+        premap_key: key in the input dict for the input (i.e., "params")
+        postmap_key: key in the output dict for the output (i.e., "output")
     """
 
     @abstractmethod
     def __init__(self, premap_key: str = "input", postmap_key: str = "output") -> None:
-        """
-        A `Map` minimally sets the premap and postmap keys.
+        """Initialize the `Map`.
 
-        #### Args
-        - premap_key (str): key in the input dict for the input (i.e., "params")
-        - postmap_key (str): key in the output dict for the output (i.e., "output")
-        """
+        A `Map` minimally sets the premap and postmap keys."""
         super().__init__()
         # TODO: make this default, maybe use @property
         self.locator = BlobLocator()
 
     @abstractmethod
     def map(self, input: Dict) -> Dict:
-        """Maps input to output.
+        """Map input to output.
 
         A `Map` operates on regular Python dicts, but it views them as
         structured. The `premap_key` and `postmap_key` are used to define
@@ -41,12 +41,11 @@ def map(self, input: Dict) -> Dict:
         Whether or not the `premap_key` exists in the output dict is up to the
         implementation of the specific `Map`. We recommend preserving it.
 
-        #### Args
-        - input (dict): generic dict containing input data to the map at
-            `premap_key`
-        #### Returns
-        - output (dict): generic dict containing output data from the map at
-            `postmap_key`
+        Args:
+            input:
+                generic dict containing input data to the map at `premap_key`
+        Returns:
+            A  dict containing output data from the map at `postmap_key`
         """
         raise NotImplementedError
 
@@ -62,8 +61,8 @@ def sample(self) -> Any:
         passes through. Then, they implement a `sample` method which returns
         a random sample of the latent representation they have encoded.
 
-        #### Returns
-        - sample (Any): a random sample of the latent representation, in
-            whatever format depending on the implementation of the `Map`
+        Returns:
+            A random sample of the latent representation, in whatever format
+            depending on the implementation of the `Map`
         """
         raise NotImplementedError

services/base/AutoDiscServer/libs/auto_disc/auto_disc/maps/__init__.py

@@ -1,3 +1,4 @@
+"""See the documentation for the `auto_disc.auto_disc.maps.Map` abstract class for details."""
 from .MeanBehaviorMap import MeanBehaviorMap
 from .NEATParameterMap import NEATParameterMap
 from .UniformParameterMap import UniformParameterMap

services/base/AutoDiscServer/libs/auto_disc/auto_disc/systems/System.py

@@ -40,12 +40,11 @@ def map(self, input: Dict) -> Dict:
         Whether or not the `premap_key` exists in the output dict is up to the
         implementation of the specific `System`. We recommend preserving it.
 
-        #### Args
-        - input (dict): generic dict containing input data to the map at
-            `premap_key`
-        #### Returns
-        - output (dict): generic dict containing output data from the map at
-            `postmap_key`
+        Args:
+            input (dict):
+                generic dict containing input data to the map at `premap_key`
+        Returns:
+            A generic dict containing output data from the map at `postmap_key`
         """
         raise NotImplementedError
 
@@ -57,12 +56,14 @@ def render(self, data_dict: dict) -> bytes:
         execution (e.g., a plot, a video, etc.), which may depend on its
         internal state which is not captured by the `map` method.
 
-        #### Args
-        - self (System): If the `System` can render a graphical output without
-            needing access to its internal state (i.e., only from the
-            output), then it can also be `@classmethod`.
-        - data_dict (dict): this is a dict containing the output of the `map`
-            method. Depending on implementation, this may be sufficient to
-            render the output or one may need stateful data from `self`.
+        Args:
+            self (System):
+                If the `System` can render a graphical output without
+                needing access to its internal state (i.e., only from the
+                output), then it can also be `@classmethod`.
+            data_dict (dict):
+                A dict containing the output of the `map`
+                method. Depending on implementation, this may be sufficient to
+                render the output or one may need stateful data from `self`.
         """
         raise NotImplementedError

services/base/AutoDiscServer/libs/auto_disc/auto_disc/systems/__init__.py

@@ -0,0 +1 @@
+"""See the documentation for the `auto_disc.auto_disc.systems.System` abstract class for details."""

services/base/AutoDiscServer/libs/auto_disc/auto_disc/utils/callbacks/__init__.py

@@ -0,0 +1,7 @@
+"""At certain defined points in the exploration loop, the software executes
+callbacks which may be user defined. Such callbacks are mostly used for doing
+environment setup and teardown, for saving output, or for accepting user input.
+
+For details on when each callback is called, look in the source for
+`auto_disc.ExperimentPipeline`
+"""

services/base/AutoDiscServer/libs/auto_disc/auto_disc/wrappers/__init__.py

@@ -1,3 +1,26 @@
+"""A collection of useful "pure" functions which wrap computational steps, for
+convenience.
+
+Essentially identical in functionality to the interface of
+`auto_disc.auto_disc.maps.Map`, but wrappers are reusable and do not have a
+particular role in the context of the exploration loop. Consequently, wrappers
+may be used to do most of the computational work inside a given `Map`,
+conceptually similar to the layers of a deep neural network. For example:
+``` python
+class MyMap(Map):
+
+    def __init__(*args):
+        super().__init__()
+        self.a = MyWrapper(args[0])
+        self.b = MyWrapper(args[1])
+
+    def map(self, input: Dict) -> Dict:
+        return self.b.map(self.a.map(input))
+
+    def sample(self) -> Any:
+        return self.b.sample()
+```
+"""
 from .IdentityWrapper import IdentityWrapper
 from .SaveWrapper import SaveWrapper
 from .TransformWrapper import TransformWrapper

services/base/AutoDiscServer/libs/docs/README_ADD_CALLBACK.md

@@ -36,7 +36,7 @@ To add a new callback create the file in the associated folder
    ```
     A full example:
     ```
-        from auto_disc.utils.callbacks.on_discovery_callbacks import BaseOnDiscoveryCallback
+        from auto_disc.legacy.utils.callbacks.on_discovery_callbacks import BaseOnDiscoveryCallback
         
         class MyBeautifullNewOnDiscoveryCallback(BaseOnDiscoveryCallback):