Enforce google docstrings (#2294)

* further updates

* Update benchmarks/WolfSheep/__init__.py

* Update __init__.py

* remove methods from class docstrings and make attributes bulleted lists

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update model.py

* enforce google docstring

* first pass for fixing all ruff issues with enforced google benchmarks

* fix space.py for google docstring standard

* ongoing fixes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fixes to model.py and time.py

* further fixes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fixes for cellspaces

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update utils.py

* Update conf.py

add extensin for parsing google docstring

* minor fixes

* last outstanding fixes in mesa source code

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* start of fixing docstrings in tests

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* remaining test fixes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update test_batch_run.py

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fixes for typos

* made noqa's more explicit

* Update fetch_unlabeled_prs.py

* Update wolf_sheep.py

* fixed all noqa directives

* Update conf.py

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: quaquel

benchmarks/BoltzmannWealth/__init__.py

@@ -0,0 +1 @@
+"""init file for BoltzmannWealth module."""

benchmarks/BoltzmannWealth/boltzmann_wealth.py

@@ -1,8 +1,21 @@
-# https://github.com/projectmesa/mesa-examples/blob/main/examples/boltzmann_wealth_model_experimental/model.py
+"""boltmann wealth model for performance benchmarking.
+
+https://github.com/projectmesa/mesa-examples/blob/main/examples/boltzmann_wealth_model_experimental/model.py
+"""
+
 import mesa
 
 
 def compute_gini(model):
+    """Calculate gini for wealth in model.
+
+    Args:
+        model: a Model instance
+
+    Returns:
+        float: gini score
+
+    """
     agent_wealths = [agent.wealth for agent in model.agents]
     x = sorted(agent_wealths)
     n = model.num_agents
@@ -19,7 +32,15 @@ class BoltzmannWealth(mesa.Model):
     """
 
     def __init__(self, seed=None, n=100, width=10, height=10):
-        super().__init__()
+        """Initializes the model.
+
+        Args:
+            seed: the seed for random number generator
+            n: the number of agents
+            width: the width of the grid
+            height: the height of the grid
+        """
+        super().__init__(seed)
         self.num_agents = n
         self.grid = mesa.space.MultiGrid(width, height, True)
         self.schedule = mesa.time.RandomActivation(self)
@@ -38,11 +59,18 @@ def __init__(self, seed=None, n=100, width=10, height=10):
         self.datacollector.collect(self)
 
     def step(self):
+        """Run the model for a single step."""
         self.agents.shuffle().do("step")
         # collect data
         self.datacollector.collect(self)
 
     def run_model(self, n):
+        """Run the model for n steps.
+
+        Args:
+            n: the number of steps for which to run the model
+
+        """
         for _i in range(n):
             self.step()
 
@@ -51,17 +79,24 @@ class MoneyAgent(mesa.Agent):
     """An agent with fixed initial wealth."""
 
     def __init__(self, model):
+        """Instantiate an agent.
+
+        Args:
+            model: a Model instance
+        """
         super().__init__(model)
         self.wealth = 1
 
     def move(self):
+        """Move the agent to a random neighboring cell."""
         possible_steps = self.model.grid.get_neighborhood(
             self.pos, moore=True, include_center=False
         )
         new_position = self.random.choice(possible_steps)
         self.model.grid.move_agent(self, new_position)
 
     def give_money(self):
+        """Give money to a random cell mate."""
         cellmates = self.model.grid.get_cell_list_contents([self.pos])
         cellmates.pop(
             cellmates.index(self)
@@ -72,6 +107,7 @@ def give_money(self):
             self.wealth -= 1
 
     def step(self):
+        """Run the agent for 1 step."""
         self.move()
         if self.wealth > 0:
             self.give_money()

benchmarks/Flocking/__init__.py

@@ -0,0 +1 @@
+"""initi for flocking benchmark model."""

benchmarks/Flocking/flocking.py

@@ -1,7 +1,5 @@
-"""
-Flockers
-=============================================================
-A Mesa implementation of Craig Reynolds's Boids flocker model.
+"""A Mesa implementation of Craig Reynolds's Boids flocker model.
+
 Uses numpy arrays to represent vectors.
 """
 
@@ -11,8 +9,7 @@
 
 
 class Boid(mesa.Agent):
-    """
-    A Boid-style flocker agent.
+    """A Boid-style flocker agent.
 
     The agent follows three behaviors to flock:
         - Cohesion: steering towards neighboring agents.
@@ -36,10 +33,10 @@ def __init__(
         separate=0.015,
         match=0.05,
     ):
-        """
-        Create a new Boid flocker agent.
+        """Create a new Boid flocker agent.
 
         Args:
+            model: a Model instance
             speed: Distance to move per step.
             direction: numpy vector for the Boid's direction of movement.
             vision: Radius to look around for nearby Boids.
@@ -59,10 +56,7 @@ def __init__(
         self.match_factor = match
 
     def step(self):
-        """
-        Get the Boid's neighbors, compute the new vector, and move accordingly.
-        """
-
+        """Get the Boid's neighbors, compute the new vector, and move accordingly."""
         neighbors = self.model.space.get_neighbors(self.pos, self.vision, False)
         n = 0
         match_vector, separation_vector, cohere = np.zeros((3, 2))
@@ -84,9 +78,7 @@ def step(self):
 
 
 class BoidFlockers(mesa.Model):
-    """
-    Flocker model class. Handles agent creation, placement and scheduling.
-    """
+    """Flocker model class. Handles agent creation, placement and scheduling."""
 
     def __init__(
         self,
@@ -102,18 +94,21 @@ def __init__(
         match=0.05,
         simulator=None,
     ):
-        """
-        Create a new Flockers model.
+        """Create a new Flockers model.
 
         Args:
+            seed: seed for random number generator
             population: Number of Boids
-            width, height: Size of the space.
+            width: the width of the space
+            height: the height of the space
             speed: How fast should the Boids move.
             vision: How far around should each Boid look for its neighbors
-            separation: What's the minimum distance each Boid will attempt to
-                    keep from any other
-            cohere, separate, match: factors for the relative importance of
+            separation: What's the minimum distance each Boid will attempt to keep from any other
+            cohere: the relative importance of matching neighbors' positions'
+            separate: the relative importance of avoiding close neighbors
+            match: factors for the relative importance of
                     the three drives.
+            simulator: a Simulator Instance
         """
         super().__init__(seed=seed)
         self.population = population
@@ -146,6 +141,7 @@ def __init__(
             self.schedule.add(boid)
 
     def step(self):
+        """Run the model for one step."""
         self.schedule.step()
 
 

benchmarks/Schelling/__init__.py

@@ -0,0 +1 @@
+"""Schelling separation for performance benchmarking."""

benchmarks/Schelling/schelling.py

@@ -1,26 +1,29 @@
+"""Schelling separation for performance benchmarking."""
+
 from mesa import Model
 from mesa.experimental.cell_space import CellAgent, OrthogonalMooreGrid
 from mesa.time import RandomActivation
 
 
 class SchellingAgent(CellAgent):
-    """
-    Schelling segregation agent
-    """
+    """Schelling segregation agent."""
 
     def __init__(self, model, agent_type, radius, homophily):
-        """
-        Create a new Schelling agent.
+        """Create a new Schelling agent.
+
         Args:
-           x, y: Agent initial location.
-           agent_type: Indicator for the agent's type (minority=1, majority=0)
+            model: model instance
+            agent_type: type of agent (minority=1, majority=0)
+            radius: size of neighborhood of agent
+            homophily: fraction of neighbors of the same type that triggers movement
         """
         super().__init__(model)
         self.type = agent_type
         self.radius = radius
         self.homophily = homophily
 
     def step(self):
+        """Run one step of the agent."""
         similar = 0
         neighborhood = self.cell.neighborhood(radius=self.radius)
         for neighbor in neighborhood.agents:
@@ -35,9 +38,7 @@ def step(self):
 
 
 class Schelling(Model):
-    """
-    Model class for the Schelling segregation model.
-    """
+    """Model class for the Schelling segregation model."""
 
     def __init__(
         self,
@@ -50,16 +51,17 @@ def __init__(
         seed=None,
         simulator=None,
     ):
-        """
-        Create a new Schelling model.
+        """Create a new Schelling model.
 
         Args:
-            height, width: Size of the space.
-            density: Initial Chance for a cell to populated
-            minority_pc: Chances for an agent to be in minority class
+            height: height of the grid
+            width: width of the grid
             homophily: Minimum number of agents of same class needed to be happy
             radius: Search radius for checking similarity
-            seed: Seed for Reproducibility
+            density: Initial Chance for a cell to populated
+            minority_pc: Chances for an agent to be in minority class
+            seed: the seed for the random number generator
+            simulator: a simulator instance
         """
         super().__init__(seed=seed)
         self.minority_pc = minority_pc
@@ -85,9 +87,7 @@ def __init__(
                 self.schedule.add(agent)
 
     def step(self):
-        """
-        Run one step of the model.
-        """
+        """Run one step of the model."""
         self.happy = 0  # Reset counter of happy agents
         self.schedule.step()
 

benchmarks/WolfSheep/__init__.py

@@ -0,0 +1 @@
+"""Wolf-Sheep Predation Model for performance benchmarking."""