docs: overhaul docs

.gitignore

@@ -189,3 +189,4 @@ GEMINI.md
 .agent/
 tools/scripts/detect_mcp_tools.py
 .geminiignore
+.agents/

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
       - id: unasyncd
         additional_dependencies: ["ruff"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.15.5"
+    rev: "v0.15.7"
     hooks:
       # Run the linter.
       - id: ruff

Makefile

@@ -10,6 +10,17 @@ SHELL := /bin/bash
 .EXPORT_ALL_VARIABLES:
 MAKEFLAGS += --no-print-directory
 
+DOC_TEST_FILES := \
+	docs/usage/modeling/basics.rst \
+	docs/usage/modeling/inheritance.rst \
+	docs/usage/modeling/sqlmodel.rst \
+	docs/usage/modeling/types.rst \
+	docs/usage/repositories/advanced.rst \
+	docs/usage/repositories/basics.rst \
+	docs/usage/repositories/filtering.rst \
+	docs/usage/database_seeding.rst \
+	docs/usage/services.rst
+
 # -----------------------------------------------------------------------------
 # Display Formatting and Colors
 # -----------------------------------------------------------------------------
@@ -142,16 +153,22 @@ clean:                                              ## Cleanup temporary build a
 # Testing and Quality Checks
 # =============================================================================
 
+.PHONY: docs-test
+docs-test:                                         ## Run executable documentation examples
+	@echo "${INFO} Running executable documentation examples... 📚"
+	@uv run pytest $(DOC_TEST_FILES) --quiet
+	@echo "${OK} Documentation examples passed ✨"
+
 .PHONY: test
 test:                                              ## Run the tests
 	@echo "${INFO} Running test cases... 🧪"
-	@uv run pytest --dist "loadgroup" -m "" tests -n 2 --quiet
+	@uv run pytest --dist "loadgroup" -m "" -n 2 --quiet
 	@echo "${OK} Tests passed ✨"
 
 .PHONY: coverage
 coverage:                                          ## Run tests with coverage report
 	@echo "${INFO} Running tests with coverage... 📊"
-	@uv run pytest tests --dist "loadgroup" -m "" --cov=advanced_alchemy --cov-report=xml -n 2 --quiet
+	@uv run pytest --dist "loadgroup" -m "" --cov=advanced_alchemy --cov-report=xml -n 2 --quiet
 	@uv run coverage html >/dev/null 2>&1
 	@echo "${OK} Coverage report generated ✨"
 

docs/PYPI_README.md

@@ -30,6 +30,10 @@ offering:
 - Integration with major web frameworks including Litestar, Starlette, FastAPI, Sanic
 - Custom-built alembic configuration and CLI with optional framework integration
 - Utility base classes with audit columns, primary keys and utility functions
+- [SQLModel](https://sqlmodel.tiangolo.com/) compatibility — use `SQLModel` `table=True` models directly with repositories and services
+- Composite primary key support — work with multi-column primary keys across repositories, services, and bulk operations
+- Read/write replica routing with automatic query routing, round-robin/random replica selection, and sticky-primary mode
+- Dogpile caching integration for query result caching
 - Built in `File Object` data type for storing objects:
     - Unified interface for various storage backends ([`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) and [`obstore`](https://developmentseed.org/obstore/latest/))
     - Optional lifecycle event hooks integrated with SQLAlchemy's event system to automatically save and delete files as records are inserted, updated, or deleted.
@@ -43,7 +47,7 @@ offering:
 - Synchronous and asynchronous repositories featuring:
     - Common CRUD operations for SQLAlchemy models
     - Bulk inserts, updates, upserts, and deletes with dialect-specific enhancements
-    - Integrated counts, pagination, sorting, filtering with `LIKE`, `IN`, and dates before and/or after.
+    - Integrated counts, pagination, sorting, filtering with `LIKE`, `IN`, `IS NULL`/`IS NOT NULL`, and dates before and/or after.
 - Tested support for multiple database backends including:
     - SQLite via [aiosqlite](https://aiosqlite.omnilib.dev/en/stable/) or [sqlite](https://docs.python.org/3/library/sqlite3.html)
     - Postgres via [asyncpg](https://magicstack.github.io/asyncpg/current/) or [psycopg3 (async or sync)](https://www.psycopg.org/psycopg3/)