Merge pull request #202 from AresSC2/docs/comvert-docstrings

fix: convert numpy style docstrings to google type

mkdocs.yml

@@ -86,7 +86,7 @@ plugins:
         python:
           paths: [src]
           selection:
-            docstring_style: numpy
+            docstring_style: google
           rendering:
             show_root_heading: false
             show_root_full_path: false

src/ares/behaviors/behavior.py

@@ -12,19 +12,14 @@ class Behavior(Protocol):
     def execute(self, ai: "AresBot", config: dict, mediator: ManagerMediator) -> bool:
         """Execute the implemented behavior.
 
-        Parameters
-        ----------
-        ai :
-            Bot object that will be running the game.
-        config :
-            Dictionary with the data from the configuration file.
-        mediator :
-            ManagerMediator used for getting information from other managers.
-
-        Returns
-        -------
-        bool :
-            Return value depends on combat / macro behavior interfaces.
+        Parameters:
+            ai: Bot object that will be running the game.
+            config: Dictionary with the data from the configuration file.
+            mediator: ManagerMediator used for getting information from other managers.
+
+        Returns:
+            bool: Return value depends on combat/macros behavior interfaces.
             See those interfaces for more info.
+
         """
         ...

src/ares/behaviors/combat/combat_behavior.py

@@ -16,18 +16,13 @@ def execute(self, ai: "AresBot", config: dict, mediator: ManagerMediator) -> boo
         Compared to CombatBehavior a MacroBehavior may be a larger isolated task.
         No need to return anything for a macro behavior.
 
-        Parameters
-        ----------
-        ai :
-            Bot object that will be running the game.
-        config :
-            Dictionary with the data from the configuration file.
-        mediator :
-            ManagerMediator used for getting information from other managers.
-
-        Returns
-        ----------
-        bool :
-            MacroBehavior carried out an action.
+        Args:
+            ai: Bot object that will be running the game.
+            config: Dictionary with the data from the configuration file.
+            mediator: ManagerMediator used for getting information from other managers.
+
+        Returns:
+            bool: MacroBehavior carried out an action.
+
         """
         ...

src/ares/behaviors/combat/combat_maneuver.py

@@ -76,10 +76,9 @@ async def on_step(self, iteration):
             self.register_behavior(mine_drop)
     ```
 
-    Attributes
-    ----------
-    micros : list[Behavior] (optional, default: [])
-        A list of behaviors that should be executed. (Optional)
+    Attributes:
+        micros: A list of behaviors that should be executed. Defaults to an empty list.
+
     """
 
     micros: list[Behavior] = field(default_factory=list)
@@ -91,14 +90,9 @@ def add(
         ],
     ) -> None:
         """
-        Parameters
-        ----------
-        behavior : CombatBehavior
-            Add a new combat behavior to the current maneuver object.
-
-        Returns
-        -------
-            None
+        Args:
+            behavior: Add a new combat behavior to the current maneuver object.
+
         """
         self.micros.append(behavior)
 

src/ares/behaviors/combat/group/a_move_group.py

@@ -24,14 +24,10 @@ class AMoveGroup(CombatGroupBehavior):
     self.register_behavior(AMoveGroup(units, self.game_info.map_center))
     ```
 
-    Attributes
-    ----------
-    group : list[Unit]
-        Units we want to control.
-    group_tags : set[int]
-        The group unit tags.
-    target: Point2
-        Where the unit is going.
+    Attributes:
+        group (list[Unit]): Units we want to control.
+        group_tags (set[int]): The group unit tags.
+        target (Point2): Where the unit is going.
     """
 
     group: list[Unit]

src/ares/behaviors/combat/group/combat_group_behavior.py

@@ -18,19 +18,13 @@ class CombatGroupBehavior(Behavior, Protocol):
     def execute(self, ai: "AresBot", config: dict, mediator: ManagerMediator) -> bool:
         """Execute the implemented behavior.
 
-        Parameters
-        ----------
-        ai :
-            Bot object that will be running the game.
-        config :
-            Dictionary with the data from the configuration file.
-        mediator :
-            ManagerMediator used for getting information from other managers.
+        Parameters:
+            ai (AresBot): AresBot instance
+            config (dict): Dictionary with the data from the configuration file.
+            mediator (ManagerMediator): Mediator instance
 
-        Returns
-        ----------
-        bool :
-            CombatGroupBehavior carried out an action.
+        Returns:
+            bool: CombatGroupBehavior carried out an action.
         """
         ...
 

src/ares/behaviors/combat/group/group_use_ability.py

@@ -30,24 +30,19 @@ class GroupUseAbility(CombatGroupBehavior):
     )
     ```
 
-    Attributes
-    ----------
-    ability: AbilityId
-        Ability we want to use.
-    group : list[Unit]
-        Units we want to control.
-    group_tags : set[int]
-        The group unit tags.
-    target: Union[Point2, Unit, None]
-        The target for this ability.
-    sync_command: bool (default=True)
-        If True, wait for all units to be ready before trying ability
+    Attributes:
+        ability: Ability we want to use.
+        group: Units we want to control.
+        group_tags: The group unit tags.
+        target: The target for this ability.
+        sync_command: (default=True) If True, wait for all units
+            to be ready before trying ability.
     """
 
     ability: AbilityId
     group: list[Unit]
     group_tags: set[int]
-    target: Union[Point2, Unit]
+    target: Union[Point2, Unit, None]
     sync_command: bool = True
 
     def execute(self, ai: "AresBot", config: dict, mediator: ManagerMediator) -> bool:

src/ares/behaviors/combat/group/keep_group_safe.py

@@ -24,16 +24,13 @@ class KeepGroupSafe(CombatGroupBehavior):
     self.register_behavior(AMoveGroup(units, self.game_info.map_center))
     ```
 
-    Attributes
-    ----------
-    group : list[Unit]
-        Units we want to control.
-    close_enemy : Union[Units, list[Unit]]
-        Nearby enemy.
-    grid : np.ndarray
-        Grid we should check for safety.
-    attack_in_range_enemy : bool (default=True)
-        Attack in range if weapon is ready.
+    Attributes:
+        group: Units we want to control.
+        close_enemy: Nearby enemy.
+        grid: Grid we should check for safety.
+        attack_in_range_enemy: Whether to attack in range if weapon is ready.
+            Defaults to True.
+
     """
 
     group: list[Unit]

src/ares/behaviors/combat/group/path_group_to_target.py

@@ -37,32 +37,24 @@ class PathGroupToTarget(CombatGroupBehavior):
     )
     ```
 
-    Attributes
-    ----------
-    start : Point2
-        Where to start the path query.
-    group: list[Unit]
-        The actual group units.
-    group_tags : set[int]
-        The units to path.
-    grid : np.ndarray
-        2D Grid to path on.
-    target : Point2
-        Target destination.
-    success_at_distance : float (default: 0.0)
-        If unit has got this close, consider path behavior complete.
-    sensitivity : int (default: 5)
-        Path precision.
-    smoothing : bool (default: False)
-        Smooth out the path.
-    sense_danger : bool (default: False)
-        Check for dangers, if none are present pathing query is skipped.
-    danger_distance : float (default: 20.0)
-        If sense_danger=True, how far to check for dangers?
-    danger_threshold : float (default: 5.0)
-        Influence at which a danger is respected.
-    prevent_duplicate : bool (default: True)
-        Try to prevent spamming action.
+    Attributes:
+        start: Where to start the path query.
+        group: The actual group units.
+        group_tags: The units to path.
+        grid: 2D grid to path on.
+        target: Target destination.
+        success_at_distance: If the unit has gotten this close,
+            consider the path behavior complete. Defaults to 0.0.
+        sensitivity: Path precision. Defaults to 5.
+        smoothing: Whether to smooth out the path. Defaults to False.
+        sense_danger: Whether to check for dangers. If none are present,
+            the pathing query is skipped. Defaults to False.
+        danger_distance: If `sense_danger` is True, how far to check for dangers.
+            Defaults to 20.0.
+        danger_threshold: Influence at which a danger is respected.
+            Defaults to 5.0.
+        prevent_duplicate: Whether to try to prevent spamming actions.
+            Defaults to True.
     """
 
     start: Point2

src/ares/behaviors/combat/group/stutter_group_back.py

@@ -30,18 +30,13 @@ class StutterGroupBack(CombatGroupBehavior):
     """Stutter a group back in unison.
 
 
-    Attributes
-    ----------
-    group : Unit
-        The group of units we want to control.
-    group_tags: Point2
-        The group unit tags.
-    group_position : Point2
-        The position where this group is situated.
-    target : Union[Point2, Unit]
-        Target for the group.
-    grid : np.ndarray
-        Grid this group will use to path on.
+    Attributes:
+        group: The group of units we want to control.
+        group_tags: The group unit tags.
+        group_position: The position where this group is situated.
+        target: Target for the group.
+        grid: Grid this group will use to path on.
+
     """
 
     group: list[Unit]
@@ -70,7 +65,7 @@ def execute(self, ai: "AresBot", config: dict, mediator: ManagerMediator) -> boo
             if group_safe:
                 return True
             if len(self.group) > 1:
-                move_to_target: Point2 = self.calculate_retreat_position(ai)
+                move_to_target: Point2 = self._calculate_retreat_position(ai)
                 safe_spot: Point2 = mediator.find_closest_safe_spot(
                     from_pos=move_to_target, grid=self.grid
                 )
@@ -100,18 +95,8 @@ def execute(self, ai: "AresBot", config: dict, mediator: ManagerMediator) -> boo
 
         return True
 
-    def calculate_retreat_position(self, ai: "AresBot") -> Point2:
-        """
-        Search 8 directions for somewhere to retreat to.
-
-        Parameters
-        ----------
-        ai
-
-        Returns
-        -------
-
-        """
+    def _calculate_retreat_position(self, ai: "AresBot") -> Point2:
+        """Search 8 directions for somewhere to retreat to."""
         distance = len(self.group) * 1.5
 
         map_bounds = ai.game_info.map_size

src/ares/behaviors/combat/group/stutter_group_forward.py

@@ -18,19 +18,13 @@
 class StutterGroupForward(CombatGroupBehavior):
     """Stutter a group forward in unison.
 
-    Attributes
-    ----------
-    group : list[Unit]
-        The group of units we want to control.
-    group_tags: set[int]
-        The group unit tags.
-    group_position : Point2
-        The position where this group is situated.
-    target : Union[Point2, Unit]
-        Target for the group.
-        Used if no enemies present.
-    enemies : Union[Units, list[Unit]]
-        The enemy units we want to stutter towards
+    Attributes:
+        group: The group of units we want to control.
+        group_tags: The group unit tags.
+        group_position: The position where this group is situated.
+        target: Target for the group, used if no enemies are present.
+        enemies: The enemy units we want to stutter towards.
+
     """
 
     group: list[Unit]

src/ares/behaviors/combat/individual/a_move.py

@@ -24,12 +24,10 @@ class AMove(CombatIndividualBehavior):
     self.register_behavior(AMove(unit, self.game_info.map_center))
     ```
 
-    Attributes
-    ----------
-    unit : Unit
-        The unit to stay safe.
-    target: Point2
-        Where the unit is going.
+    Attributes:
+        unit: The unit to stay safe.
+        target: Where the unit is going.
+
     """
 
     unit: Unit

src/ares/behaviors/combat/individual/attack_target.py

@@ -25,12 +25,10 @@ class AttackTarget(CombatIndividualBehavior):
     self.register_behavior(AttackTarget(unit, target))
     ```
 
-    Attributes
-    ----------
-    unit: Unit
-        The unit to shoot.
-    target : Unit
-        The unit we want to shoot at.
+    Attributes:
+        unit: The unit to shoot.
+        target: The unit we want to shoot at.
+
     """
 
     unit: Unit

src/ares/behaviors/combat/individual/combat_individual_behavior.py

@@ -16,19 +16,14 @@ def execute(self, ai: "AresBot", config: dict, mediator: ManagerMediator) -> boo
         Compared to CombatBehavior a MacroBehavior may be a larger isolated task.
         No need to return anything for a macro behavior.
 
-        Parameters
-        ----------
-        ai :
-            Bot object that will be running the game.
-        config :
-            Dictionary with the data from the configuration file.
-        mediator :
-            ManagerMediator used for getting information from other managers.
-
-        Returns
-        ----------
-        bool :
-            True if this CombatIndividualBehavior carried out an action.
-            False otherwise.
+        Args:
+            ai: Bot object that will be running the game.
+            config: Dictionary with the data from the configuration file.
+            mediator: ManagerMediator used for getting information from other managers.
+
+        Returns:
+            bool: True if this CombatIndividualBehavior carried out an action,
+                False otherwise.
+
         """
         ...