feat(docs): add sphinx documentation with autoapi for 17-package monorepo

Scaffold: docs/conf.py (sphinx-autoapi + myst-parser + furo), Makefile,
make.bat, .readthedocs.yaml. Per-package guide pages: 3 rich-doc wrappers
(cqrs-core, sqlalchemy-repos, outbox-core) with {include} of existing .md,
14 new guides for README-only packages. Top-level: index.rst, quickstart,
architecture, exception-comparison.

Deps bumped to latest stable (Python 3.10 compatible):
- sphinx 7->8.1, myst-parser 3->4, furo 2024->2025
- black 23->26, ruff 0.1->0.15, pytest-asyncio 0.23->1.3
- mypy 1.5->1.19, hypothesis 6.100->6.151

Minor myst compatibility fixes in existing docs (transition removal,
code fence language tags, docstring condensing).

Author: FirstUnicorn

.gitignore

@@ -7,6 +7,8 @@ __pycache__/
 build/
 develop-eggs/
 dist/
+dist2/
+dist*/
 downloads/
 eggs/
 .eggs/
@@ -25,6 +27,7 @@ venv/
 ENV/
 env/
 .venv
+tmp_venv/
 
 # IDEs
 .vscode/
@@ -55,4 +58,8 @@ dmypy.json
 *.tar.gz
 
 # Distribution artifacts
-*.whl
+*.whl
+
+# Sphinx docs
+docs/_build/
+docs/autoapi/

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/Makefile

@@ -0,0 +1,12 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/architecture.md

@@ -0,0 +1,61 @@
+# Architecture
+
+## Layer hierarchy
+
+```
+Application layer (depends on Domain + Primitives)
+├── python-mediator
+├── python-cqrs-dispatcher (depends on cqrs-core + mediator)
+├── fastapi-config-patterns
+├── fastapi-middleware-toolkit
+├── python-structlog-config
+├── python-outbox-core
+├── sqlalchemy-async-session-factory
+└── sqlalchemy-async-repositories
+
+Domain layer (depends on Primitives only)
+├── python-app-exceptions
+├── python-infrastructure-exceptions
+├── python-input-validation
+├── python-cqrs-core
+├── python-domain-events
+├── python-dto-mappers
+└── pydantic-response-models
+
+Primitives layer (zero dependencies)
+└── python-technical-primitives
+```
+
+## Import-linter contracts
+
+Layer boundaries are enforced via `import-linter` in `pyproject.toml`:
+
+- **Primitives** cannot import from domain or application
+- **Domain** can import from primitives, cannot import from application
+- **Application** can import from domain and primitives
+
+## Inter-package dependencies
+
+Only one cross-package dependency exists:
+
+```
+python-cqrs-dispatcher
+├── python-cqrs-core (ICommand, IQuery interfaces)
+└── python-mediator  (Mediator dispatch engine)
+```
+
+All other packages are fully independent.
+
+## Design patterns used
+
+| Pattern | Package |
+|---------|---------|
+| Specification | `python-technical-primitives` |
+| Repository + Strategy | `sqlalchemy-async-repositories` |
+| Factory Method | `sqlalchemy-async-repositories` (pagination) |
+| Mediator | `python-mediator` |
+| CQRS | `python-cqrs-core`, `python-cqrs-dispatcher` |
+| Pipeline behaviors | `python-mediator` |
+| Transactional outbox | `python-outbox-core` |
+| Strategy (formatters) | `python-outbox-core` |
+| CloudEvents | `python-outbox-core` |

docs/conf.py

@@ -0,0 +1,57 @@
+"""Sphinx configuration for python-web-toolkit monorepo."""
+import os
+import sys
+
+project = "python-web-toolkit"
+copyright = "2026, GridFlow"
+author = "GridFlow"
+
+extensions = [
+    "autoapi.extension",
+    "myst_parser",
+    "sphinx_copybutton",
+]
+
+autoapi_dirs = [
+    f"../packages/{pkg}/src"
+    for pkg in [
+        "python-technical-primitives",
+        "python-app-exceptions",
+        "python-infrastructure-exceptions",
+        "python-input-validation",
+        "postgres-data-sanitizers",
+        "pydantic-response-models",
+        "python-cqrs-core",
+        "python-mediator",
+        "python-cqrs-dispatcher",
+        "python-dto-mappers",
+        "python-domain-events",
+        "python-structlog-config",
+        "fastapi-config-patterns",
+        "fastapi-middleware-toolkit",
+        "python-outbox-core",
+        "sqlalchemy-async-session-factory",
+        "sqlalchemy-async-repositories",
+    ]
+]
+autoapi_type = "python"
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+]
+autoapi_keep_files = True
+
+myst_enable_extensions = ["colon_fence", "deflist"]
+myst_heading_anchors = 3
+
+html_theme = "furo"
+html_static_path = ["_static"]
+templates_path = ["_templates"]
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
+
+suppress_warnings = ["myst.header", "myst.xref_missing"]

docs/exception-comparison.md

@@ -0,0 +1,3 @@
+```{include} ../packages/EXCEPTION_LIBRARIES_COMPARISON.md
+:relative-images:
+```

docs/index.rst

@@ -0,0 +1,29 @@
+python-web-toolkit
+==================
+
+17-package Python monorepo for building async web applications with FastAPI, SQLAlchemy, CQRS, and domain-driven design.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting started
+
+   quickstart
+   architecture
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Packages
+
+   packages/index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Comparisons
+
+   exception-comparison
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API reference
+
+   autoapi/index

docs/make.bat

@@ -0,0 +1,25 @@
+@ECHO OFF
+pushd %~dp0
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.sphinx-build not found.
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/packages/fastapi-config-patterns.md

@@ -0,0 +1,28 @@
+# fastapi-config-patterns
+
+Reusable Pydantic settings classes for FastAPI applications.
+
+## Installation
+
+```bash
+pip install fastapi-config-patterns
+```
+
+## Public API
+
+| Class/Function | Purpose |
+|----------------|---------|
+| `BaseFastAPISettings` | Base settings with `app_name`, `debug`, `allowed_origins`, env loading |
+| `BaseDatabaseSettings` | Database settings mixin (`database_url`, pool config) |
+| `assemble_cors_origins(v)` | Parse CORS origins from string or list |
+
+## Usage
+
+```python
+from fastapi_config_patterns import BaseFastAPISettings, BaseDatabaseSettings
+
+class Settings(BaseFastAPISettings, BaseDatabaseSettings):
+    redis_url: str = "redis://localhost"
+
+settings = Settings()  # loads from environment / .env
+```

docs/packages/fastapi-middleware-toolkit.md

@@ -0,0 +1,36 @@
+# fastapi-middleware-toolkit
+
+Reusable FastAPI middleware: CORS, error handlers, cache control, lifespan, health checks.
+
+## Installation
+
+```bash
+pip install fastapi-middleware-toolkit
+```
+
+## Public API
+
+| Function/Class | Purpose |
+|----------------|---------|
+| `setup_cors_middleware(app, allowed_origins, ...)` | CORS with secure defaults |
+| `setup_error_handlers(app, custom_exception_class)` | Global error handlers |
+| `CacheControlMiddleware` | Default Cache-Control headers |
+| `setup_cache_control_middleware(app)` | Register cache control |
+| `create_lifespan_manager(on_startup, on_shutdown)` | Lifespan context manager |
+| `create_health_check_endpoint(service_name, version)` | Health check factory |
+
+## Usage
+
+```python
+from fastapi import FastAPI
+from fastapi_middleware_toolkit import (
+    setup_cors_middleware,
+    setup_error_handlers,
+    create_lifespan_manager,
+)
+
+lifespan = create_lifespan_manager(service_name="api")
+app = FastAPI(lifespan=lifespan)
+setup_cors_middleware(app, ["http://localhost:3000"])
+setup_error_handlers(app)
+```