adding documentation and fixing issue #111

CHANGELOG.rst

@@ -16,6 +16,11 @@ Change Log
 - [???] modeled dumps in grid2op (stuff that have a given energy max, and cannot produce more than the available energy)
 - [???] fix notebook 5 texts
 
+[1.0.0] - 2020-06-xx
+---------------------
+- [UPDATED] `Issue #111 <https://github.com/rte-france/Grid2Op/issues/111>`_ Converter is better documented to be
+  more broadly usable.
+
 [0.9.3] - 2020-05-29
 ---------------------
 - [FIXED] `Issue #69 <https://github.com/rte-france/Grid2Op/issues/69>`_ MultEnvironment is now working with windows

grid2op/Converter/IdToAct.py

@@ -80,12 +80,21 @@ def init_converter(self, all_actions=None, **kwargs):
 
         Parameters
         ----------
-        all_actions: ``list``
-            The (ordered) list of all actions that the agent will be able to perform. If given a number ``i`` the
-            converter will return action ``all_actions[i]``. In the "pacman" game, this vector could be
-            ["up", "down", "left", "right"], in this case "up" would be encode by 0, "down" by 1, "left" by 2 and
-            "right" by 3. If nothing is provided, the converter will output all the unary actions possible for
-            the environment. Be careful, computing all these actions might take some time.
+        all_actions: ``None``, ``list``, ``str``, ``np.ndarray``
+            See the example section for more informations.
+
+            if `all_actions` is:
+
+                - ``None``: the action space will be built from scratch using the provided key word arguments.
+                - a ``list``: The (ordered) list of all actions that the agent will be able to perform.
+                  If given a number ``i`` the
+                  converter will return action ``all_actions[i]``. In the "pacman" game, this vector could be
+                  ["up", "down", "left", "right"], in this case "up" would be encode by 0, "down" by 1, "left" by 2 and
+                  "right" by 3. If nothing is provided, the converter will output all the unary actions possible for
+                  the environment. Be careful, computing all these actions might take some time.
+                - a ``str`` this will be considered as a path where a previous converter has been saved. You need to
+                  provide the full path, including the filename and its extension. It gives something like:
+                  "/path/where/it/is/saved/action_space_vect.npy"
 
         kwargs:
             other keyword arguments (all considered to be ``True`` by default) that can be:
@@ -114,6 +123,38 @@ def init_converter(self, all_actions=None, **kwargs):
                 Whether you want to include the "redispatch" in your action space
                 (in case the original action space allows it)
 
+
+        Examples
+        --------
+        Here is an example of a code that will: make a converter by selecting some action. Save it, and then restore
+        its original state to be used elsewhere.
+
+        .. code-block:: python
+
+            import grid2op
+            from grid2op.Converter import IdToAct
+            env = grid2op.make()
+            converter = IdToAct(env.action_space)
+
+            # the path were will save it
+            path_ = "/path/where/it/is/saved/"
+            name_file = "tmp_convert.npy"
+
+            # init the converter, the first time, here by passing some key word arguments, to not consider
+            # redispatching for example
+            converter.init_converter(redispatch=False)
+            converter.save(path_, name_file)
+
+            # i just do an action, for example the number 27... whatever it does does not matter here
+            act = converter.convert_act(27)
+
+            converter2 = IdToAct(self.env.action_space)
+            converter2.init_converter(all_actions=os.path.join(path_, name_file))
+            act2 = converter2.convert_act(27)
+
+            assert act ==  act2  # this is ``True`` the converter has properly been saved.
+
+
         """
         self.kwargs_init = kwargs
         if all_actions is None:
@@ -226,8 +267,35 @@ def save(self, path, name="action_space_vect.npy"):
         name: ``str``, optional
             The name of the numpy array stored on disk. By default its "action_space_vect.npy"
 
-        Returns
-        -------
+        Examples
+        --------
+        Here is an example of a code that will: make a converter by selecting some action. Save it, and then restore
+        its original state to be used elsewhere.
+
+        .. code-block:: python
+
+            import grid2op
+            from grid2op.Converter import IdToAct
+            env = grid2op.make()
+            converter = IdToAct(env.action_space)
+
+            # the path were will save it
+            path_ = "/path/where/it/is/saved/"
+            name_file = "tmp_convert.npy"
+
+            # init the converter, the first time, here by passing some key word arguments, to not consider
+            # redispatching for example
+            converter.init_converter(redispatch=False)
+            converter.save(path_, name_file)
+
+            # i just do an action, for example the number 27... whatever it does does not matter here
+            act = converter.convert_act(27)
+
+            converter2 = IdToAct(self.env.action_space)
+            converter2.init_converter(all_actions=os.path.join(path_, name_file))
+            act2 = converter2.convert_act(27)
+
+            assert act ==  act2  # this is ``True`` the converter has properly been saved.
 
         """
         if not os.path.exists(path):