docs: fix warnings

day01/day1a.py

@@ -13,15 +13,12 @@ def get_first_last(line: str) -> tuple[str, str]:
     It can be the same character.
 
     Args:
-    ----
         line (str): string to parse
 
     Raises:
-    ------
         ValueError: When there are no numbers in the string
 
     Returns:
-    -------
         tuple[str, str]: first char, last char
     """
     first: Optional[str] = None
@@ -41,11 +38,9 @@ def get_input(input_file: str) -> list[str]:
     """Grabs list of lines to parse from input file.
 
     Args:
-    ----
         input_file (str): input file's name
 
     Returns:
-    -------
         list[str]: list of lines to parse
     """
     with open(input_file, "r", encoding="utf8") as file:
@@ -56,11 +51,9 @@ def part1(lines: list[str]) -> int:
     """Runs day1/part1 of adventofcode2023.
 
     Args:
-    ----
         lines (list[str]): list of lines to parse
 
     Returns:
-    -------
         int: sum of results for each line.
     """
     total = 0

day02/day2.py

@@ -93,7 +93,7 @@ def get_games(input_file: str) -> list[Game]:
         input_file (str): input file name
 
     Returns:
-        list[Game]: list of ``Game``s
+        list[Game]: list of Games
     """
     with open(input_file, "r", encoding="utf8") as file:
         games: list[Game] = []

day14/day14.py

@@ -63,10 +63,10 @@ def correct_side(self) -> "World":
 
 
 def naive_score(world_rows: list[str]) -> int:
-    """Returns score assuming west is pointing left.
+    r"""Returns score assuming west is pointing left.
 
     For each row, a round boulder ``O``'s score is
-    ``num_rows`` minus its ``index``(higher weight to the left.)
+    ``num_rows`` minus its ``index`` (higher weight to the left.)
     """
     num_rows = len(world_rows)
     score = 0

day15/lib/classes.py

@@ -38,7 +38,7 @@ def __str__(self) -> str:
 
 @dataclass
 class Box:
-    """Box can contain a variety of ``Lens``es."""
+    r"""Box can contain a variety of ``Lens``\es."""
 
     id: int = 0
     contents: list[Lens] = field(default_factory=list)

day16/lib/__init__.py

@@ -0,0 +1 @@
+"""library modules for day16."""

day16/lib/cells.py

@@ -1,16 +1,18 @@
-"""Cell classes
-"""
+"""Cell classes."""
 from abc import ABC, abstractmethod
 
 from day16.lib.direction import Direction
 from day16.lib.laser import Laser
 
 
 class Cell(ABC):
+    """Abstract cell class."""
+
     contents: str
 
     @staticmethod
     def construct(contents: str) -> "Cell":
+        """Construct proper cell from given contents."""
         if contents == ".":
             return DotCell()
         elif contents == "|":
@@ -25,23 +27,32 @@ def construct(contents: str) -> "Cell":
 
     @abstractmethod
     def next_lasers(self, laser: Laser) -> list[Laser]:
+        """Return next lasers given a laser entering this cell."""
         raise AssertionError("Not supported", laser)
 
 
 class DotCell(Cell):
+    """A dot cell."""
+
     def __init__(self) -> None:
+        """Sets our contents to ``.``."""
         self.contents = "."
 
     def next_lasers(self, laser: Laser) -> list[Laser]:
+        """Lasers pass directly through this tile."""
         row, col = laser.direction.offset(laser.row, laser.col)
         return [Laser(row, col, laser.direction)]
 
 
 class DashCell(Cell):
+    """A ``-`` cell."""
+
     def __init__(self) -> None:
+        """Sets our contents to ``-``."""
         self.contents = "-"
 
     def next_lasers(self, laser: Laser) -> list[Laser]:
+        """Lasers must end up going east/west after passing through this cell."""
         if laser.direction in [Direction.EAST, Direction.WEST]:
             row, col = laser.direction.offset(laser.row, laser.col)
             return [Laser(row, col, laser.direction)]
@@ -55,10 +66,14 @@ def next_lasers(self, laser: Laser) -> list[Laser]:
 
 
 class PipeCell(Cell):
+    """A ``|`` cell."""
+
     def __init__(self) -> None:
+        """Sets our contents to ``|``."""
         self.contents = "|"
 
     def next_lasers(self, laser: Laser) -> list[Laser]:
+        """Lasers must end up going north/south after passing through this cell."""
         if laser.direction in [Direction.NORTH, Direction.SOUTH]:
             row, col = laser.direction.offset(laser.row, laser.col)
             return [Laser(row, col, laser.direction)]
@@ -72,10 +87,14 @@ def next_lasers(self, laser: Laser) -> list[Laser]:
 
 
 class ForwardSlashCell(Cell):
+    """A ``/`` cell."""
+
     def __init__(self) -> None:
+        """Sets our contents to ``/``."""
         self.contents = "/"
 
     def next_lasers(self, laser: Laser) -> list[Laser]:
+        """Lasers go diagonal mode."""
         row, col = laser.row, laser.col
         if laser.direction == Direction.EAST:
             return [Laser(row - 1, col, Direction.NORTH)]
@@ -89,10 +108,14 @@ def next_lasers(self, laser: Laser) -> list[Laser]:
 
 
 class BackSlashCell(Cell):
+    r"""A ``\`` cell."""
+
     def __init__(self) -> None:
+        r"""Sets our contents to ``\``."""
         self.contents = "\\"
 
     def next_lasers(self, laser: Laser) -> list[Laser]:
+        """Lasers go diagonal mode."""
         row, col = laser.row, laser.col
         if laser.direction == Direction.EAST:
             return [Laser(row + 1, col, Direction.SOUTH)]

docs/conf.py

@@ -23,6 +23,12 @@
     "sphinx.ext.viewcode",
 ]
 
+suppress_warnings = [
+    # This is here to prevent:
+    #  "WARNING: more than one target found for cross-reference"
+    "ref.python",
+]
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]