docs: add Google-style docstrings and Sphinx autodoc setup

Add concise docstrings to all Python modules, classes, and public
functions. Configure Sphinx with napoleon extension for Google-style
docstring parsing and autodoc pages for each module.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Mathew Sir Guest the best
2026-05-06 23:06:37 -06:00
co-authored by Claude Opus 4.6
parent fd3ff46804
commit 4d681a92ca
16 changed files with 479 additions and 0 deletions
+21
View File
@@ -1,3 +1,5 @@
"""Board generation for word search puzzles."""
import random
import string
@@ -19,10 +21,29 @@ MAX_PLACEMENT_ATTEMPTS = 100
class BoardFactory:
"""Generates word search boards from category word lists.
Args:
session: SQLAlchemy session for querying category words.
"""
def __init__(self, session):
self.session = session
def create(self, category_id, board_size=10, word_count=8):
"""Generate a new game board.
Selects random words from the category, places them on the grid
in random directions, and fills remaining cells with random letters.
Args:
category_id: ID of the category to pull words from.
board_size: Grid dimension (N x N).
word_count: Maximum number of words to place.
Returns:
Tuple of (Game, list[Word]) with objects not yet committed.
"""
candidates = (
self.session.query(CategoryWord)
.filter(CategoryWord.category_id == category_id)