chore: add changelog and documentation updates

- Created a new `CHANGELOG.md` file to document all notable changes to the project, adhering to the Keep a Changelog format.
- Updated `CONTRIBUTING.md` to include instructions for building and previewing documentation using MkDocs.
- Added `mkdocs.yml` configuration for documentation generation, including navigation structure and theme settings.
- Enhanced various documentation files, including API reference, architecture overview, configuration reference, and runbook, to provide comprehensive guidance for users and developers.
- Included new sections in the README for changelog and documentation links, improving accessibility to project information.

duty_teller/db/session.py

@@ -21,7 +21,14 @@ _SessionLocal = None
 
 @contextmanager
 def session_scope(database_url: str) -> Generator[Session, None, None]:
-    """Context manager: yields a session, rolls back on exception, closes on exit."""
+    """Context manager that yields a session; rolls back on exception, closes on exit.
+
+    Args:
+        database_url: SQLAlchemy database URL.
+
+    Yields:
+        Session instance. Caller must not use it after exit.
+    """
     session = get_session(database_url)
     try:
         yield session
@@ -33,6 +40,7 @@ def session_scope(database_url: str) -> Generator[Session, None, None]:
 
 
 def get_engine(database_url: str):
+    """Return cached SQLAlchemy engine for the given URL (one per process)."""
     global _engine
     if _engine is None:
         _engine = create_engine(
@@ -46,6 +54,7 @@ def get_engine(database_url: str):
 
 
 def get_session_factory(database_url: str) -> sessionmaker[Session]:
+    """Return cached session factory for the given URL (one per process)."""
     global _SessionLocal
     if _SessionLocal is None:
         engine = get_engine(database_url)
@@ -54,4 +63,5 @@ def get_session_factory(database_url: str) -> sessionmaker[Session]:
 
 
 def get_session(database_url: str) -> Session:
+    """Create a new session from the factory for the given URL."""
     return get_session_factory(database_url)()