migrate function param documentation to reStructuredText format

grilops/grids.py

@@ -8,15 +8,7 @@
 
 
 class SymbolGrid:
-  """A grid of cells that can be solved to contain specific symbols.
-
-  Args:
-    lattice (grilops.geometry.Lattice): The structure of the grid.
-    symbol_set (grilops.symbols.SymbolSet): The set of symbols to be filled
-      into the grid.
-    solver (Optional[z3.Solver]): A `Solver` object. If None, a `Solver` will
-      be constructed.
-  """
+  """A grid of cells that can be solved to contain specific symbols."""
   _instance_index = 0
 
   def __init__(
@@ -25,6 +17,11 @@ def __init__(
       symbol_set: SymbolSet,
       solver: Optional[Solver] = None
   ):
+    """
+    :param lattice: The structure of the grid.
+    :param symbol_set: The set of symbols to be filled into the grid.
+    :param solver: A `Solver` object. If None, a `Solver` will be constructed.
+    """
     SymbolGrid._instance_index += 1
     if solver:
       self.__solver = solver
@@ -62,12 +59,10 @@ def lattice(self) -> Lattice:
   def edge_sharing_neighbors(self, p: Point) -> List[Neighbor]:
     """Returns a list of cells that share an edge with the given cell.
 
-    Args:
-      p (grilops.geometry.Point): The location of the given cell.
+    :param p: The location of the given cell.
 
-    Returns:
-      A `List[grilops.geometry.Neighbor]` representing the cells sharing an
-        edge with the given cell.
+    :return: A `List[grilops.geometry.Neighbor]` representing the cells sharing
+      an edge with the given cell.
     """
     return self.__lattice.edge_sharing_neighbors(self.__grid, p)
 
@@ -77,38 +72,32 @@ def vertex_sharing_neighbors(self, p: Point) -> List[Neighbor]:
     In other words, returns a list of cells orthogonally and diagonally
     adjacent to the given cell.
 
-    Args:
-      p (grilops.geometry.Point): The location of the given cell.
+    :param p: The location of the given cell.
 
-    Returns:
-      A `List[grilops.geometry.Neighbor]` representing the cells sharing an
-        vertex with the given cell.
+    :return: A `List[grilops.geometry.Neighbor]` representing the cells sharing
+      a vertex with the given cell.
     """
     return self.__lattice.vertex_sharing_neighbors(self.__grid, p)
 
   def cell_is(self, p: Point, value: int) -> BoolRef:
     """Returns an expression for whether this cell contains this value.
 
-    Args:
-      p (grilops.geometry.Point): The location of the given cell.
-      value (int): The value to satisfy the expression.
+    :param p: The location of the given cell.
+    :param value: The value to satisfy the expression.
 
-    Returns:
-      An expression that's true if and only if the cell at p contains this
-        value.
+    :return: An expression that's true if and only if the cell at p contains
+      this value.
     """
     return self.__grid[p] == value
 
   def cell_is_one_of(self, p: Point, values: Iterable[int]) -> BoolRef:
     """Returns an expression for whether this cell contains one of these values.
 
-    Args:
-      p (grilops.geometry.Point): The location of the given cell.
-      values (Iterable[int]): The set of values to satisfy the expression.
+    :param p: The location of the given cell.
+    :param values: The set of values to satisfy the expression.
 
-    Returns:
-      An expression that's true if and only if the cell at p contains one of
-        these values.
+    :return: An expression that's true if and only if the cell at p contains
+      one of these values.
     """
     cell = self.__grid[p]
     return Or(*[cell == value for value in values])
@@ -147,13 +136,11 @@ def print(self, hook_function: Optional[Callable[[Point, int], str]] = None):
     Should be called only after `SymbolGrid.solve` has already completed
     successfully.
 
-    Args:
-      hook_function (Optional[Callable[[grilops.geometry.Point, int], str]]): A
-        function implementing custom symbol display behavior, or None. If
-        this function is provided, it will be called for each cell in the grid,
-        with the arguments p (`grilops.geometry.Point`) and the symbol index
-        for that cell (`int`). It may return a string to print for that cell,
-        or None to keep the default behavior.
+    :param hook_function: A function implementing custom symbol display
+      behavior, or None. If this function is provided, it will be called for
+      each cell in the grid, with the arguments p (`grilops.geometry.Point`)
+      and the symbol index for that cell (`int`). It may return a string to
+      print for that cell, or None to keep the default behavior.
     """
     model = self.__solver.model()
     label_width = max(len(s.label) for s in self.__symbol_set.symbols.values())

grilops/loops.py

@@ -34,38 +34,35 @@ class LoopSymbolSet(PathSymbolSet):
   Additional symbols (e.g. a `grilops.symbols.Symbol` representing an empty
   space) may be added to this `grilops.symbols.SymbolSet` by calling
   `grilops.symbols.SymbolSet.append` after it's constructed.
-
-  Args:
-    lattice (grilops.geometry.Lattice): The structure of the grid.
   """
 
   def __init__(self, lattice: Lattice):
+    """
+    :param lattice: The structure of the grid.
+    """
     super().__init__(lattice, include_terminals=False)
 
   def is_loop(self, symbol: ArithRef) -> BoolRef:
     """Returns true if the given symbol represents part of the loop.
 
-    Args:
-      symbol (ArithRef): An `ArithRef` expression representing a symbol.
+    :param symbol: An `ArithRef` expression representing a symbol.
 
-    Returns:
-      A true `BoolRef` if the symbol represents part of the loop.
+    :return: A true `BoolRef` if the symbol represents part of the loop.
     """
     return self.is_path_segment(symbol)
 
 
 class LoopConstrainer(PathConstrainer):
-  """Creates constraints for ensuring symbols form closed loops.
-
-  Args:
-    symbol_grid (grilops.grids.SymbolGrid): The grid to constrain.
-    single_loop (bool): If true, constrain the grid to contain only a single loop.
-  """
+  """Creates constraints for ensuring symbols form closed loops."""
   def __init__(
       self,
       symbol_grid: SymbolGrid,
       single_loop: bool = False,
   ):
+    """
+    :param symbol_grid: The grid to constrain.
+    :param single_loop: If true, constrain the grid to contain only a single loop.
+    """
     super().__init__(symbol_grid, allow_terminated_paths=False)
     self.__symbol_grid = symbol_grid
 

grilops/paths.py

@@ -22,14 +22,14 @@ class PathSymbolSet(SymbolSet):
   Additional symbols (e.g. a `grilops.symbols.Symbol` representing an empty
   space) may be added to this `grilops.symbols.SymbolSet` by calling
   `grilops.symbols.SymbolSet.append` after it's constructed.
-
-  Args:
-    lattice (grilops.geometry.Lattice): The structure of the grid.
-    include_terminals (bool): If True, create symbols for path terminals.
-      Defaults to True.
   """
 
   def __init__(self, lattice: Lattice, include_terminals: bool = True):
+    """
+    :param lattice: The structure of the grid.
+    :param include_terminals: If True, create symbols for path terminals.
+      Defaults to True.
+    """
     super().__init__([])
     self.__include_terminals = include_terminals
 
@@ -59,11 +59,9 @@ def __init__(self, lattice: Lattice, include_terminals: bool = True):
   def is_path(self, symbol: ArithRef) -> BoolRef:
     """Returns true if the given symbol represents part of a path.
 
-    Args:
-      symbol (ArithRef): An `ArithRef` expression representing a symbol.
+    :param symbol: An `ArithRef` expression representing a symbol.
 
-    Returns:
-      A true `BoolRef` if the symbol represents part of a path.
+    :return: A true `BoolRef` if the symbol represents part of a path.
     """
     if self.__include_terminals:
       return symbol < self.__max_path_terminal_symbol_index + 1
@@ -72,22 +70,19 @@ def is_path(self, symbol: ArithRef) -> BoolRef:
   def is_path_segment(self, symbol: ArithRef) -> BoolRef:
     """Returns true if the given symbol represents a non-terminal path segment.
 
-    Args:
-      symbol (ArithRef): An `ArithRef` expression representing a symbol.
+    :param symbol: An `ArithRef` expression representing a symbol.
 
-    Returns:
-      A true `BoolRef` if the symbol represents a non-terminal path segment.
+    :return: A true `BoolRef` if the symbol represents a non-terminal path
+      segment.
     """
     return symbol < self.__max_path_segment_symbol_index + 1
 
   def is_terminal(self, symbol: ArithRef) -> BoolRef:
     """Returns true if the given symbol represents a path terminal.
 
-    Args:
-      symbol (ArithRef): An `ArithRef` expression representing a symbol.
+    :param symbol: An `ArithRef` expression representing a symbol.
 
-    Returns:
-      A true `BoolRef` if the symbol represents a path terminal
+    :return: A true `BoolRef` if the symbol represents a path terminal.
     """
     if not self.__include_terminals:
       return BoolVal(False)
@@ -99,52 +94,37 @@ def is_terminal(self, symbol: ArithRef) -> BoolRef:
   def symbols_for_direction(self, d: Direction) -> List[int]:
     """Returns the symbols with one arm going in the given direction.
 
-    Args:
-      d (grilops.geometry.Direction): The given direction.
+    :param d: The given direction.
 
-    Returns:
-      A `List[int]` of symbol indices corresponding to symbols with one arm
-      going in the given direction.
+    :return: A `List[int]` of symbol indices corresponding to symbols with one
+      arm going in the given direction.
     """
     return self.__symbols_for_direction[d]
 
   def symbol_for_direction_pair(self, d1: Direction, d2: Direction) -> int:
     """Returns the symbol with arms going in the two given directions.
 
-    Args:
-      d1 (grilops.geometry.Direction): The first given direction.
-      d2 (grilops.geometry.Direction): The second given direction.
+    :param d1: The first given direction.
+    :param d2: The second given direction.
 
-    Returns:
-      The symbol index for the symbol with one arm going in each of the two
-      given directions.
+    :return: The symbol index for the symbol with one arm going in each of the
+      two given directions.
     """
     return self.__symbol_for_direction_pair[(d1, d2)]
 
   def terminal_for_direction(self, d: Direction) -> int:
     """Returns the symbol that terminates the path from the given direction.
 
-    Args:
-      d (grilops.geometry.Direction): The given direction.
+    :param d: The given direction.
 
-    Returns:
-      The symbol index for the symbol that terminates the path from the given
-      direction.
+    :return: The symbol index for the symbol that terminates the path from the
+      given direction.
     """
     return self.__terminal_for_direction[d]
 
 
 class PathConstrainer:
-  """Creates constraints for ensuring symbols form connected paths.
-
-  Args:
-    symbol_grid (grilops.grids.SymbolGrid): The grid to constrain.
-    complete (bool): If True, every cell must be part of a path.
-      Defaults to False.
-    allow_terminated_paths (bool): If True, finds paths that are terminated
-      (not loops). Defaults to True.
-    allow_loops (bool): If True, finds paths that are loops. Defaults to True.
-  """
+  """Creates constraints for ensuring symbols form connected paths."""
   _instance_index = 0
 
   def __init__(
@@ -154,6 +134,14 @@ def __init__(
       allow_terminated_paths: bool = True,
       allow_loops: bool = True,
   ):
+    """
+    :param symbol_grid: The grid to constrain.
+    :param complete: If True, every cell must be part of a path. Defaults to
+      False.
+    :param allow_terminated_paths: If True, finds paths that are terminated
+      (not loops). Defaults to True.
+    :param allow_loops: If True, finds paths that are loops. Defaults to True.
+    """
     PathConstrainer._instance_index += 1
 
     self.__symbol_grid = symbol_grid

grilops/regions.py

@@ -23,21 +23,7 @@
 
 
 class RegionConstrainer:  # pylint: disable=R0902
-  """Creates constraints for grouping cells into contiguous regions.
-
-  Args:
-    lattice (grilops.geometry.Lattice): The structure of the grid.
-    solver (Optional[z3.Solver]): A `Solver` object. If None, a `Solver` will be
-      constructed.
-    complete (bool): If true, every cell must be part of a region. Defaults to
-      true.
-    rectangular (bool): If true, every region must be "rectangular"; for each
-      cell in a region, ensure that pairs of its neighbors that are part of
-      the same region each share an additional neighbor that's part of the
-      same region when possible.
-    min_region_size (Optional[int]): The minimum possible size of a region.
-    max_region_size (Optional[int]): The maximum possible size of a region.
-  """
+  """Creates constraints for grouping cells into contiguous regions."""
   _instance_index = 0
 
   def __init__(  # pylint: disable=R0913
@@ -49,6 +35,18 @@ def __init__(  # pylint: disable=R0913
       min_region_size: Optional[int] = None,
       max_region_size: Optional[int] = None
   ):
+    """
+    :param lattice: The structure of the grid.
+    :param solver: A `Solver` object. If None, a `Solver` will be constructed.
+    :param complete: If true, every cell must be part of a region. Defaults to
+      true.
+    :param rectangular: If true, every region must be "rectangular"; for each
+      cell in a region, ensure that pairs of its neighbors that are part of
+      the same region each share an additional neighbor that's part of the
+      same region when possible.
+    :param min_region_size: The minimum possible size of a region.
+    :param max_region_size: The maximum possible size of a region.
+    """
     RegionConstrainer._instance_index += 1
     self.__lattice = lattice
     if solver:
@@ -214,12 +212,10 @@ def edge_sharing_direction_to_index(self, direction: Direction) -> int:
 
     For instance, if direction is (-1, 0), return the index for N.
 
-    Args:
-      direction (grilops.geometry.Direction): The direction to an edge-sharing cell.
+    :param direction: The direction to an edge-sharing cell.
 
-    Returns:
-      The `RegionConstrainer.parent_grid` value that means that the parent
-        in its region's subtree is the cell offset by that direction.
+    :return: The `RegionConstrainer.parent_grid` value that means that the
+      parent in its region's subtree is the cell offset by that direction.
     """
     return self.__edge_sharing_direction_to_index[direction]
 
@@ -229,11 +225,9 @@ def parent_type_to_index(self, parent_type: str) -> int:
     The parent_type may be a direction name (like "N") or name of a special
     value like "R" or "X".
 
-    Args:
-      parent_type (str): The parent type.
+    :param parent_type: The parent type.
 
-    Returns:
-      The corresponding `RegionConstrainer.parent_grid` value.
+    :return: The corresponding `RegionConstrainer.parent_grid` value.
     """
     return self.__parent_type_to_index[parent_type]