Update docstrings in Gymnasium/Gym wrappers

Farama-Foundation · Dec 15, 2023 · de4b248 · de4b248
1 parent 96d3f6f
commit de4b248
Show file tree

Hide file tree

Showing 8 changed files with 76 additions and 58 deletions.
diff --git a/docs/api/cpp/doomGame.md b/docs/api/cpp/doomGame.md
@@ -55,7 +55,7 @@ Note: Changed in 1.1.0
 | Python | `replay_episode(file_path: str, player: int = 0) -> None`            |
 
 Replays the recorded episode from the given file using the perspective of the specified player.
-Players are numbered from 1, If `player` argument is equal to 0, 
+Players are numbered from 1, If `player` argument is equal to 0,
 the episode will be replayed using the perspective of the default player in the recording file.
 After calling this method, the first state from the replay will be available.
 All rewards, variables, and states are available when replaying the episode.
@@ -172,7 +172,7 @@ Returns true if the current episode is in the initial state - the first state, n
 | Python | `is_episode_finished() -> bool` |
 
 Returns true if the current episode is in the terminal state (is finished).
-[`makeAction`](#makeaction) and [`advanceAction`](#advanceaction) methods 
+[`makeAction`](#makeaction) and [`advanceAction`](#advanceaction) methods
 will take no effect after this point (unless [`newEpisode`](#newepisode) method is called).
 
 
@@ -251,7 +251,7 @@ Note: added in 1.1.6.
 | Python | `get_last_action() -> list`           |
 
 Returns the last action performed.
-Each value corresponds to a button added with [`setAvailableButtons`](#setAvailableButtons) 
+Each value corresponds to a button added with [`setAvailableButtons`](#setAvailableButtons)
 or/and [`addAvailableButton`](#addAvailableButton) (in order of appearance).
 Most useful in `SPECTATOR` mode.
 
@@ -1526,4 +1526,4 @@ See also:
 - [`GameState`](./gameState.md#gamestate)
 - [examples/python/audio_buffer.py](https://github.com/Farama-Foundation/ViZDoom/tree/master/examples/python/audio_buffer.py)
 
-Note: added in 1.1.9.
+Note: added in 1.1.9.
diff --git a/docs/api/cpp/enums.md b/docs/api/cpp/enums.md
@@ -178,8 +178,8 @@ Enum type that defines all variables that can be obtained from the game.
 ACS global int variables can be accessed as USER GameVariables.
 global int 0 is reserved for reward and is always treated as Doom's fixed point numeral.
 Other from 1 to 60 (global int 1-60) can be accessed as USER1 - USER60 GameVariables.
-If you assign fixed point numeral to USER1 - USER60 GameVariables, 
-you can convert them to floating point by using [`doomFixedToDouble`](utils.md#doomfixedtodouble) function. 
+If you assign fixed point numeral to USER1 - USER60 GameVariables,
+you can convert them to floating point by using [`doomFixedToDouble`](utils.md#doomfixedtodouble) function.
 
 See also:
 - [ZDoom Wiki: ACS](http://zdoom.org/wiki/ACS),

diff --git a/docs/api/python/enums.md b/docs/api/python/enums.md
@@ -123,8 +123,8 @@ Enum type that defines all variables that can be obtained from the game. Below w
 - **USER1** - **USER60**    - user defined variables. ACS global int variables can be accessed as USER GameVariables.
 global int 0 is reserved for reward and is always threaded as Doom fixed point numeral.
 Other from 1 to 60 (global int 1-60) can be accessed as USER1 - USER60 GameVariables.
-If you assign fixed point numeral to USER1 - USER60 GameVariables, 
-you can convert them to floating point by using [`doom_fixed_to_float`](./utils.md#vizdoom.doom_fixed_to_float) function. 
+If you assign fixed point numeral to USER1 - USER60 GameVariables,
+you can convert them to floating point by using [`doom_fixed_to_float`](./utils.md#vizdoom.doom_fixed_to_float) function.
 
 See also:
 - [ZDoom Wiki: ACS](http://zdoom.org/wiki/ACS),

diff --git a/docs/api/python/gym.md b/docs/api/python/gym.md
@@ -1,6 +1,6 @@
 # OpenAI Gym Env
 
-> Gym is deprecated in favor of Gymnasium and these wrappers will be removed in the future. 
+> Gym is deprecated in favor of Gymnasium and these wrappers will be removed in the future.
 Please consider migrating to Gymnasium.
 To install gym wrapper you need to run `pip install vizdoom[gym]` as it is not installed by default.
 

diff --git a/gym_wrapper/base_gym_env.py b/gym_wrapper/base_gym_env.py
@@ -48,18 +48,20 @@ def __init__(
 
         Observations are dictionaries with different amount of entries, depending on if depth/label buffers were
         enabled in the config file (CHANNELS == 1 if GRAY8, else 3):
-          "screen"        = the screen image buffer (always available) in shape (HEIGHT, WIDTH, CHANNELS)
-          "depth"         = the depth image in shape (HEIGHT, WIDTH, 1), if enabled by the config file,
-          "labels"        = the label image buffer in shape (HEIGHT, WIDTH, 1), if enabled by the config file.
+
+        - "screen"        = the screen image buffer (always available) in shape (HEIGHT, WIDTH, CHANNELS)
+        - "depth"         = the depth image in shape (HEIGHT, WIDTH, 1), if enabled by the config file,
+        - "labels"        = the label image buffer in shape (HEIGHT, WIDTH, 1), if enabled by the config file.
                             For info on labels, access `env.state.labels` variable.
-          "automap"       = the automap image buffer in shape (HEIGHT, WIDTH, CHANNELS), if enabled by the config file
-          "gamevariables" = all game variables, in the order specified by the config file
+        - "automap"       = the automap image buffer in shape (HEIGHT, WIDTH, CHANNELS), if enabled by the config file
+        - "gamevariables" = all game variables, in the order specified by the config file
 
         Action space can be a single one of binary/continuous action space, or a Dict containing both.
-          "binary":
+
+        - "binary":
                           = MultiDiscrete([2] * num_binary_buttons): if max_buttons_pressed == 0
                           = Discrete(n): if max_buttons_pressed > 1
-          "continuous":
+        - "continuous":
                           = Box(float32.min, float32.max, (num_delta_buttons,), float32).
         """
         EzPickle.__init__(self, level, frame_skip, max_buttons_pressed, render_mode)

diff --git a/gymnasium_wrapper/base_gymnasium_env.py b/gymnasium_wrapper/base_gymnasium_env.py
@@ -37,33 +37,35 @@ def __init__(
         Child classes are defined in gym_env_defns.py,
 
         Arguments:
-            level (str): path to the config file to load. Most settings should be set by this config file.
-            frame_skip (int): how many frames should be advanced per action. 1 = take action on every frame. Default: 1.
-            max_buttons_pressed (int): defines the number of binary buttons that can be selected at once. Default: 1.
+            level (str): The path to the config file to load. Most settings should be set by this config file.
+            frame_skip (int): The number of frames the will be advanced per action. 1 = take action on every frame. Default: 1.
+            max_buttons_pressed (int): Defines the number of binary buttons that can be selected at once. Default: 1.
                                        Should be >= 0. If < 0 a RuntimeError is raised.
-                                       If == 0, the binary action space becomes MultiDiscrete([2] * num_binary_buttons)
-                                       and [0, num_binary_buttons] number of binary buttons can be selected.
-                                       If > 0, the binary action space becomes Discrete(n)
-                                       and [0, max_buttons_pressed] number of binary buttons can be selected.
-            render_mode(Optional[str]): the render mode to use could be either 'human' or 'rgb_array'
+                                       If == 0, the binary action space becomes ``MultiDiscrete([2] * num_binary_buttons)``
+                                       and [0, ``num_binary_buttons``] number of binary buttons can be selected.
+                                       If > 0, the binary action space becomes ``Discrete(n)``
+                                       and ``n`` actions can be selected.
+                                       ``n`` is equal to number of possible buttons combinations
+                                       with the number of buttons pressed < ``max_buttons_pressed``.
+            render_mode(Optional[str]): The render mode to use could be either "human" or "rgb_array"
 
-        This environment forces window to be hidden. Use `render()` function to see the game.
+        This environment forces the game window to be hidden. Use :meth:`render` function to see the game.
 
-        Observations are dictionaries with different amount of entries, depending on if depth/label buffers were
+        Observations are dictionaries with different number of entries, depending on if depth/label buffers were
         enabled in the config file (CHANNELS == 1 if GRAY8, else 3):
-          "screen"        = the screen image buffer (always available) in shape (HEIGHT, WIDTH, CHANNELS)
-          "depth"         = the depth image in shape (HEIGHT, WIDTH, 1), if enabled by the config file,
-          "labels"        = the label image buffer in shape (HEIGHT, WIDTH, 1), if enabled by the config file.
-                            For info on labels, access `env.state.labels` variable.
-          "automap"       = the automap image buffer in shape (HEIGHT, WIDTH, CHANNELS), if enabled by the config file
-          "gamevariables" = all game variables, in the order specified by the config file
-
-        Action space can be a single one of binary/continuous action space, or a Dict containing both.
-          "binary":
-                          = MultiDiscrete([2] * num_binary_buttons): if max_buttons_pressed == 0
-                          = Discrete(n): if max_buttons_pressed > 1
-          "continuous":
-                          = Box(float32.min, float32.max, (num_delta_buttons,), float32).
+
+        - "screen": The screen image buffer (always available) as `np.ndarray` in shape ``(HEIGHT, WIDTH, CHANNELS)``.
+        - "depth": The depth image as ``np.ndarray`` in shape ``(HEIGHT, WIDTH, 1)``, if enabled by the config file.
+        - "labels": The label image buffer as `np.ndarray` in shape ``(HEIGHT, WIDTH, 1)``, if enabled by the config file.
+          For info on labels, access `env.state.labels` variable.
+        - "automap": The automap image buffer as ``np.ndarray`` in shape ``(HEIGHT, WIDTH, CHANNELS)``, if enabled by the config file.
+        - "gamevariables": All game variables, in the order specified by the config file.
+
+        Action space can be a single one of binary/continuous action space, or a ``Dict`` containing both:
+
+        - "binary": Is ``MultiDiscrete([2] * num_binary_buttons)`` if :attr:`max_buttons_pressed` == 0
+          or ``Discrete(num_binary_buttons + 1)`` if :attr:`max_buttons_pressed` >= 1.
+        - "continuous": Is ``Box(float32.min, float32.max, (num_delta_buttons,), float32)``.
         """
         EzPickle.__init__(self, level, frame_skip, max_buttons_pressed, render_mode)
         self.frame_skip = frame_skip
@@ -286,7 +288,7 @@ def __parse_available_buttons(self):
         """
         Parses the currently available game buttons,
         reorganizes all delta buttons to be prior to any binary buttons
-        sets self.num_delta_buttons, self.num_binary_buttons
+        sets ``num_delta_buttons``, ``num_binary_buttons``
         """
         delta_buttons = []
         binary_buttons = []
@@ -307,7 +309,7 @@ def __parse_available_buttons(self):
 
     def __get_binary_action_space(self):
         """
-        return binary action space: either Discrete(n)/MultiDiscrete([2,]*num_binary_buttons)
+        Return binary action space: either ``Discrete(n)``/``MultiDiscrete([2] * num_binary_buttons)``
         """
         if self.max_buttons_pressed == 0:
             button_space = gym.spaces.MultiDiscrete(
@@ -327,7 +329,7 @@ def __get_binary_action_space(self):
 
     def __get_continuous_action_space(self):
         """
-        return continuous action space: Box(float32.min, float32.max, (num_delta_buttons,), float32)
+        Returns continuous action space: Box(float32.min, float32.max, (num_delta_buttons,), float32)
         """
         return gym.spaces.Box(
             np.finfo(np.float32).min,
@@ -338,11 +340,11 @@ def __get_continuous_action_space(self):
 
     def __get_action_space(self):
         """
-        return action space:
+        Returns action space:
             if both binary and delta buttons defined in the config file, action space will be:
-              Dict("binary": MultiDiscrete|Discrete, "continuous", Box)
+              ``Dict("binary": MultiDiscrete|Discrete, "continuous", Box)``
             else:
-              action space will be only one of the following MultiDiscrete|Discrete|Box
+              action space will be only one of the following ``MultiDiscrete``|``Discrete``|``Box``
         """
         if self.num_delta_buttons == 0:
             return self.__get_binary_action_space()
@@ -358,7 +360,7 @@ def __get_action_space(self):
 
     def __get_observation_space(self):
         """
-        return observation space: Dict with Box entry for each activated buffer:
+        Returns observation space: Dict with Box entry for each activated buffer:
           "screen", "depth", "labels", "automap", "gamevariables"
         """
         spaces = {

diff --git a/scripts/create_python_docs_from_cpp_docs.py b/scripts/create_python_docs_from_cpp_docs.py
@@ -22,10 +22,7 @@
 ]
 SECTION_REGEX = r"^##+ *([a-zA-Z/-:, ]+) *$"
 FUNCTION_REGEX = r"^###+ *`([a-zA-Z]+)` *$"
-TO_REPLACE = [
-    ("ViZDoom", "Vizdoom"),
-    ("doomFixedToDouble", "doomFixedToFloat")
-]
+TO_REPLACE = [("ViZDoom", "Vizdoom"), ("doomFixedToDouble", "doomFixedToFloat")]
 
 if __name__ == "__main__":
     for fp in FILES_TO_PARSE:
@@ -67,8 +64,8 @@
                         # Convert CamelCase to snake_case
                         function_name = re.sub(
                             r"(?<!^)(?=[A-Z])", "_", function_name
-                        ).lower()  
-                        
+                        ).lower()
+
                         output_file.write(
                             f".. autofunction:: vizdoom.{fp['submodule']}{function_name}\n"
                         )

diff --git a/scripts/create_python_docstrings_from_cpp_docs.py b/scripts/create_python_docstrings_from_cpp_docs.py
@@ -19,16 +19,31 @@ def camel_case_to_snake_case(text):
     ("true", "`True`"),  # Cpp -> Python bool
     ("false", "`False`"),  # Cpp -> Python bool
     ("`nullptr/null/None`", "`None`"),  # Cpp -> Python None
-    (r"\[(`[a-z][a-zA-Z]+`)?\]\(.*?\)", r":meth:\1"),  # MD methods links -> :meth:`name`
-    (r"\[`([A-Z][a-zA-Z]+)`?\]\(.*?\)", r":class:`.\1`"),  # MD object links -> :class:`name`
+    (
+        r"\[(`[a-z][a-zA-Z]+`)?\]\(.*?\)",
+        r":meth:\1",
+    ),  # MD methods links -> :meth:`name`
+    (
+        r"\[`([A-Z][a-zA-Z]+)`?\]\(.*?\)",
+        r":class:`.\1`",
+    ),  # MD object links -> :class:`name`
     (r"([^:])(`[<>/a-zA-Z0-9_\- \.,\"\']+?`)", r"\1`\2`"),  # `text` -> ``text``
-    (r"\[([a-zA-Z/_\(\):\-\. \(\)]+)?\]\((.*)?\)", r"`\1 <\2>`_"),  # MD links -> RT links
+    (
+        r"\[([a-zA-Z/_\(\):\-\. \(\)]+)?\]\((.*)?\)",
+        r"`\1 <\2>`_",
+    ),  # MD links -> RT links
     (r"\.md([#a-zA-Z\-]*)>`_", r".html\1>`_"),  # Fix links ending with .md
-    (r"^See also:.*$", "See also:\n"),  # See also: -> See also: \n (for nicer formatting of lists)
+    (
+        r"^See also:.*$",
+        "See also:\n",
+    ),  # See also: -> See also: \n (for nicer formatting of lists)
 ]
 TO_PROCESS = [
     (r":meth:`[a-z][a-zA-Z]+?`", camel_case_to_snake_case),  # CamelCase -> snake_case
-    (r"``[a-z][a-zA-Z]+?`` argument", camel_case_to_snake_case),  # CamelCase -> snake_case
+    (
+        r"``[a-z][a-zA-Z]+?`` argument",
+        camel_case_to_snake_case,
+    ),  # CamelCase -> snake_case
 ]
 LINES_TO_IGNORE_REGEXES = [
     r"---",  # Lines
@@ -89,7 +104,9 @@ def camel_case_to_snake_case(text):
                         for r in TO_REPLACE:
                             line = re.sub(r[0], r[1], line)
                         for r in TO_PROCESS:
-                            line = re.sub(r[0], lambda match: r[1](match.group(0)), line)
+                            line = re.sub(
+                                r[0], lambda match: r[1](match.group(0)), line
+                            )
                         next_docstring += line
 
             if started: