Adds README and pydocs.

Author: cbathras

README.md

@@ -0,0 +1,86 @@
+Introduction
+============
+
+Dots is an implementation of the classic game where you draw a bunch of dots on
+a piece of paper in a grid pattern and then players take turns connecting the
+dots. When a square, or cell, is made the player "captures" the cell. The player
+with the greatest number of captured cells at the end of the game wins.
+
+Dots has always been a favorite game of mine and when I decided I wanted to
+learn a little bit about game programming, I figured Dots would be a good place
+to start. Dots is simple enough that I figured I wouldn't get bogged down in the
+details of the game during implementation, but complex enough that making the
+game would give me a nice little taste of game programming. Since Python is my
+go-to language I figured Pygame would be a good place to start.
+
+Requirements
+============
+There are just two requirements for running Dots:
+
+1. Python 3.7.7 or greater (https://www.python.org/downloads/)
+2. Pygame 2.0.0 or greater (https://www.pygame.org/)
+
+During development I use Python virtual environments to isolate the Python
+version and packages I need. Feel free to use whatever you are comfortable with.
+
+Running the Game
+================
+Dots is executed from the command line. Below is the usage documentation when
+starting with the -h or --help option.
+
+```
+$ python dots.py -h
+usage: dots.py [-h] [-r ROWS] [-c COLUMNS] [-w CELL_WIDTH] [-t CELL_HEIGHT] [-p [PLAYER ...]]
+
+A pygame implementation of the classic game of trying to capture as many cells as you can by connecting the dots.
+
+optional arguments:
+    -h, --help       show this help message and exit
+    -r ROWS          number of rows of cells (default: 4)
+    -c COLUMNS       number of columns of cells (default: 4)
+    -w CELL_WIDTH    width of cells (default: 100 pixels)
+    -t CELL_HEIGHT   height of cells (default: 100 pixels)
+    -p [PLAYER ...]  names of the two to four players (default: Alice Bob)
+```
+
+As you can see, there are default values for all options so simply executing
+dots.py will run the game for you.
+
+Playing the Game
+================
+When you first start the game, the game board will look something similar to
+this:
+
+![Dots 1](docs/dots1.png)
+
+The left pointing arrow indicates whose turn it is to connect two dots. To
+connect two dots, simply move your mouse over an edge between two dots. As you
+hover over an edge, the edge will be outlined to highlight the edge as shown
+below:
+
+![Dots 2](docs/dots2.png)
+
+Click on the edge to join the two dots. Once you click on the edge it will be
+permanently colored in indicating the dots are now joined. Clicking on an edge
+that already connects two dots has no effect. After connecting two dots, it
+becomes the next player's turn. You will see the left pointing arrow now points
+at the next player.
+
+![Dots 3](docs/dots3.png)
+
+Players continue alternating connecting dots until a cell is captured by
+connecting all of the dots that make up the cell. If connecting two dots
+captures a cell, the cell's background color changes to the color of the player
+that captured the cell. The player's score also updates when a cell is captured.
+Additionally, the player that captured the cell gets to connect another two
+dots. As long as the player continues capturing cells, it remains their turn.
+
+![Dots 4](docs/dots4.png)
+
+Continue with game play until all of the cells have been captured and a winner
+is determined. At the end of the game, you will have the option to start a new
+game. Click the "Play Again?" button to start a new game.
+
+![Dots 5](docs/dots5.png)
+
+I hope you enjoy playing the game!

banner.py

@@ -1,3 +1,5 @@
+"""A banner graphic for the game of Dots."""
+
 # Copyright 2021 Curt Bathras
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -25,6 +27,9 @@
 
 
 class Banner(pg.Rect):
+    """Banner is used to create the graphic at the end of the game to display
+    the winner.
+    """
     def __init__(self, rect: pg.Rect, bg_color: pg.Color):
         super().__init__(rect)
         self.bg_color = bg_color
@@ -34,6 +39,7 @@ def __init__(self, rect: pg.Rect, bg_color: pg.Color):
             self.screen.get_height() // 2)
 
     def draw(self, winner: list[Player]) -> None:
+        """Draw the banner to the screen."""
         # Create the message text
         msg = f'{winner[0].name} Wins!' if len(winner) == 1 else "It's a TIE!"
         text = FONT_20.render(msg, True, BLACK)
@@ -50,6 +56,7 @@ def draw(self, winner: list[Player]) -> None:
         pg.display.update(self)
 
     def clear(self) -> None:
+        """Clear the banner from the screen."""
         pg.draw.rect(self.screen, BACKGROUND_COLOR, self)
 
     def __str__(self) -> str:

board.py

@@ -1,3 +1,5 @@
+"""The main board for game play in the game of Dots."""
+
 # Copyright 2021 Curt Bathras
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -29,6 +31,37 @@
 
 
 class Board:
+    """A Board is the collection of all of the entities that make up the game.
+    Namely, dots, edges, and cells. Entities are grouped into what I call
+    superrows and supercolumns. A single element, or supercell, of a superrow
+    and supercolumn is the collection of one dot, two edges and one cell. The
+    number of superrows is one greater than the number of cells in the board's
+    height and the number of supercolumns is one greater than the number of
+    cells in the board's width. Superrows and supercolumns allow for a very fast
+    lookup of which two edges could possibly contain a point in space. Once the
+    supercell is known, it is quick to check if either edge contains the point.
+
+    The diagram below illustrates the concept of a supercell. D = a dot, E = an
+    edge, C = a cell.
+
+    DDD | EEEEEEEEEEEEEEE
+    DDD | EEEEEEEEEEEEEEE
+    ---------------------
+    EEE | CCCCCCCCCCCCCCC
+    EEE | CCCCCCCCCCCCCCC
+    EEE | CCCCCCCCCCCCCCC
+    EEE | CCCCCCCCCCCCCCC
+    EEE | CCCCCCCCCCCCCCC
+    EEE | CCCCCCCCCCCCCCC
+
+    This supercell consists of one dot, two edges (one vertical and one
+    horizontal) and one cell. For the last supercolumn, the supercell only
+    contains the dot and vertical edge. For the last superrow, the supercell
+    only contains the dot and horizontal edge. The upper left corner of a
+    supercell and its height and width are well-defined. So the lookup of which
+    supercell contains a point is very fast. From there, it is at most two
+    comparisons to see if either edge contains the point.
+    """
     def __init__(self, x_shift: int=0, y_shift: int=0):
         super().__init__()
         self._cfg: Config = Config()
@@ -37,7 +70,7 @@ def __init__(self, x_shift: int=0, y_shift: int=0):
         self._screen: pg.Surface = pg.display.get_surface()
         self._highlighted_edge = None
 
-        # Create the dots
+        # Create the dots (a 2D list of Dot objects)
         self._dots: list[list[Dot]] = []
         for r in range(0, self._cfg.CELL_ROWS + 1):
             row = []
@@ -56,7 +89,7 @@ def __init__(self, x_shift: int=0, y_shift: int=0):
                 dot.draw()
             self._dots.append(row)
 
-        # Create the cells
+        # Create the cells (a 2D list of Cell objects)
         self._cells: list[list[Cell]] = []
         for r in range(0, self._cfg.CELL_ROWS):
             row = []
@@ -75,7 +108,7 @@ def __init__(self, x_shift: int=0, y_shift: int=0):
                 cell.draw()
             self._cells.append(row)
 
-        # Create the edges
+        # Create the edges (a 2D list of Edge objects)
         # Superrows and supercolumns are rows and columns of a collection
         # of one dot, two edges, and one cell. This allows for easy grouping
         # and lookup of edges based on mouse location.
@@ -98,7 +131,11 @@ def __init__(self, x_shift: int=0, y_shift: int=0):
                     )
                     h_edge.draw()
 
-                # Establish cell to edge relationships
+                # Establish cell to edge relationships - for checking whether a
+                # cell is captured by a user, we need to know which cells the
+                # edge touches. An edge always touches one or two cells. Edges
+                # that touch one cell are the edges that make up the exterior
+                # of the board.
                 # top superrow
                 if h_edge and r == 0:
                     h_edge.cell2 = self._cells[r][c]
@@ -130,7 +167,10 @@ def __init__(self, x_shift: int=0, y_shift: int=0):
                     )
                     v_edge.draw()
 
-                # Establish cell to edge relationships
+                # Establish cell to edge relationships - for checking whether a
+                # cell is captured by a user, we need to know which edges the
+                # cell touches. A cell always touches four edges: top, bottom,
+                # left and right.
                 # left supercolumn
                 if v_edge and c == 0:
                     v_edge.cell2 = self._cells[r][c]
@@ -170,6 +210,7 @@ def __init__(self, x_shift: int=0, y_shift: int=0):
         self.draw()
 
     def get_edge(self, pos: tuple) -> Edge:
+        """Retrieve the edge containing pos."""
         # To look up the edge to see if it contains the x,y you can quickly
         # retrieve the tuple of edges that possibly contains x,y by:
         # row = y // (dd + ch)
@@ -178,12 +219,14 @@ def get_edge(self, pos: tuple) -> Edge:
         # x,y
         try:
             x, y = pos
+            # Determine the superrow and supercolumn containing the point
             row = (y - self._y_shift - self._cfg.GUTTER_WIDTH) // \
                 (self._cfg.DOT_DIA + self._cfg.CELL_HEIGHT)
             col = (x - self._x_shift - self._cfg.GUTTER_WIDTH) // \
                 (self._cfg.DOT_DIA + self._cfg.CELL_WIDTH)
             edges = self._edges[row][col]
 
+            # Check to see if either edge contains the point
             for edge in edges:
                 if edge.collidepoint(pos):
                     return edge
@@ -192,6 +235,7 @@ def get_edge(self, pos: tuple) -> Edge:
             return None
 
     def highlight_edge(self, edge: Edge) -> None:
+        """Highlight the specified edge."""
         if not edge.captured and self._highlighted_edge != edge:
             if self._highlighted_edge:
                 pg.draw.rect(self._screen,
@@ -203,19 +247,22 @@ def highlight_edge(self, edge: Edge) -> None:
             self._highlighted_edge = edge
 
     def unhighlight_edge(self) -> None:
+        """Clear the highlighted edge so it is no longer highlighted."""
         if self._highlighted_edge:
             pg.draw.rect(self._screen, EDGE_COLOR_DEFAULT,
                 self._highlighted_edge)
             pg.display.update(self._highlighted_edge)
             self._highlighted_edge = None
 
     def capture_edge(self, edge: Edge) -> None:
+        """Capture the specified edge."""
         self._highlighted_edge = None
         edge.captured = True
         pg.draw.rect(self._screen, EDGE_COLOR_CAPTURED, edge)
         pg.display.update(edge)
 
     def draw(self) -> None:
+        """Draw the entire board."""
         pg.display.flip()
 
     def __str__(self) -> str:

button.py

@@ -1,3 +1,5 @@
+"""A general button implementation."""
+
 # Copyright 2021 Curt Bathras
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -28,6 +30,7 @@
 
 
 class Button:
+    """A button that a user can click that performs a function."""
     def __init__(self, pos: tuple, size: tuple, callback: callable=None,
             font: pg.font.Font=FONT_16, text: str='', visible: bool=True,
             text_color: pg.Color=WHITE, radius: int=3):
@@ -48,13 +51,16 @@ def __init__(self, pos: tuple, size: tuple, callback: callable=None,
 
     @property
     def visible(self) -> bool:
+        """Get the button visibility."""
         return self._visible
 
     @visible.setter
     def visible(self, val: bool) -> None:
+        """Set the button visibility."""
         self._visible = val
 
     def draw(self) -> None:
+        """Draw the button on the screen."""
         if self._visible:
             # Get the button's surface and draw a rectangle on it
             self._rect = self._surf.get_rect()
@@ -88,6 +94,7 @@ def draw(self) -> None:
             pg.display.update(self._rect)
 
     def handle_event(self, event: pg.event) -> None:
+        """Handle the mouse events."""
         if self._visible:
             if event.type == pg.MOUSEBUTTONDOWN:
                 if self._rect.collidepoint(event.pos):

cell.py

@@ -1,3 +1,5 @@
+"""A cell is bounded by four dots and four edges in the game of Dots."""
+
 # Copyright 2021 Curt Bathras
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -26,6 +28,11 @@
 
 
 class Cell(Entity):
+    """A Cell represents the thing a player is trying to capture. It is bounded
+    by four dots and four edges. The Cell class derives from the Entity abstract
+    base class which in turns derives from the Pygame Rect class so every Cell
+    is also a Rect.
+    """
     def __init__(self, pos: tuple, size: tuple, bg_color: pg.Color):
 
         super().__init__(pos, size, bg_color)
@@ -37,47 +44,60 @@ def __init__(self, pos: tuple, size: tuple, bg_color: pg.Color):
 
     @property
     def captured(self) -> bool:
+        """Get the captured status of the cell."""
         return self._captured
 
     @property
     def edge_top(self) -> Edge:
+        """Get the top edge associated with the cell."""
         return self._edge_top
 
     @edge_top.setter
     def edge_top(self, val) -> None:
+        """Set the top edge associated with the cell."""
         self._edge_top = val
 
     @property
     def edge_bottom(self) -> Edge:
+        """Get the bottom edge associated with the cell."""
         return self._edge_bottom
 
     @edge_bottom.setter
     def edge_bottom(self, val) -> None:
+        """Set the bottom edge associated with the cell."""
         self._edge_bottom = val
 
     @property
     def edge_right(self) -> Edge:
+        """Get the right edge associated with the cell."""
         return self._edge_right
 
     @edge_right.setter
     def edge_right(self, val) -> None:
+        """Set the right edge associated with the cell."""
         self._edge_right = val
 
     @property
     def edge_left(self) -> Edge:
+        """Get the left edge associated with the cell."""
         return self._edge_left
 
     @edge_left.setter
     def edge_left(self, val) -> None:
+        """Set the left edge associated with the cell."""
         self._edge_left = val
 
     def handle_event(self, event: pg.event) -> None:
+        """No-op implemenation because a cell handles no events."""
         return
 
     def draw(self) -> None:
+        """Draw the cell to the screen."""
         pg.draw.rect(self._screen, self._bg_color, self)
 
     def check_for_capture(self, player: Player) -> bool:
+        """Check to see if all edges associated with this cell have been
+        captured which means this cell has been captured."""
         if self._edge_top.captured and self._edge_bottom.captured \
             and self._edge_left.captured and self._edge_right.captured: