docs: add full MkDocs site, API reference, and Pages workflow

Author: SirStig

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [ main, master ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e '.[docs]'
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Deploy to GitHub Pages (gh-pages branch)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: mkdocs gh-deploy --force --clean --message "docs: deploy ${GITHUB_SHA}"

docs/api/index.md

@@ -0,0 +1,27 @@
+# API Reference
+
+## Public API
+
+::: yokedcache
+
+## Core
+
+### Cache
+
+::: yokedcache.cache
+
+### Decorators
+
+::: yokedcache.decorators
+
+### Configuration
+
+::: yokedcache.config
+
+### Models
+
+::: yokedcache.models
+
+### Utils
+
+::: yokedcache.utils

docs/architecture.md

@@ -0,0 +1,13 @@
+# Architecture
+
+```mermaid
+graph TB
+    A[FastAPI App] --> B[YokedCache Wrapper]
+    B --> C{Cache Hit?}
+    C -->|Yes| D[Return Cached Data]
+    C -->|No| E[Query Database]
+    E --> F[Store in Redis]
+    F --> G[Return Data]
+    H[Database Write] --> I[Auto-Invalidation]
+    I --> J[Clear Related Cache]
+```

docs/auto-invalidation.md

@@ -0,0 +1,33 @@
+# Auto-Invalidation
+
+YokedCache invalidates relevant cache entries on database writes so you don't serve stale data.
+
+## How it works
+
+- Wrap your DB dependency with `cached_dependency(...)`.
+- Reads (`query`, `get`, `first`, `all`) are cached with tags like `table:<name>`.
+- Writes (`execute`, `exec`) are tracked; on `commit()`, tags for affected tables are invalidated.
+
+```python
+from yokedcache import YokedCache
+from yokedcache.decorators import cached_dependency
+
+cache = YokedCache()
+cached_get_db = cached_dependency(get_db, cache=cache, ttl=300, table_name="users")
+
+# In your route handlers, use db=Depends(cached_get_db)
+```
+
+Under the hood (`yokedcache.decorators.CachedDatabaseWrapper`):
+
+- Extracts table with `extract_table_from_query()` for simple SQL patterns.
+- Adds tag `table:<table>` on cached reads.
+- On commit, calls `cache.invalidate_tags([f"table:{table}"])`.
+
+## Best practices
+
+- Pass `table_name` when you know the target table.
+- Use predictable SQL (or ORM) so table extraction works well.
+- For multi-table writes, consider multiple tags.
+- For complex cases, call `await cache.invalidate_pattern("users:*")` directly.
+

docs/cli-cookbook.md

@@ -0,0 +1,31 @@
+# CLI Cookbook
+
+## Monitor stats continuously
+
+```bash
+yokedcache stats --watch
+```
+
+## Export config
+
+```bash
+yokedcache export-config --output config.yaml
+```
+
+## List keys by prefix
+
+```bash
+yokedcache list --prefix users:
+```
+
+## Delete by pattern
+
+```bash
+yokedcache flush --pattern "users:*" --force
+```
+
+## Invalidate by tags
+
+```bash
+yokedcache flush --tags "user_data" --force
+```

docs/cli.md

@@ -0,0 +1,27 @@
+# CLI
+
+```bash
+# View cache statistics
+$ yokedcache stats --watch
+
+# Test Redis connection
+$ yokedcache ping
+
+# List cached keys
+$ yokedcache list --pattern "user:*"
+
+# Flush specific caches
+$ yokedcache flush --tags "user_data"
+
+# Search cache contents
+$ yokedcache search "alice" --threshold 80
+
+# Monitor in real-time (JSON output)
+$ yokedcache stats --format json
+
+# Export current configuration
+$ yokedcache export-config --output config.yaml
+
+# Warm cache with predefined data
+$ yokedcache warm --config-file cache_config.yaml
+```

docs/concepts.md

@@ -0,0 +1,17 @@
+# Concepts
+
+- **Cache keys**: Namespaced identifiers for cached values. Built from `key_prefix`, function/table context, and hashed args.
+- **TTL and jitter**: Each entry expires after TTL; jitter spreads expirations to avoid thundering herds.
+- **Tags**: Group keys for bulk invalidation, e.g., `table:users`.
+- **Auto-invalidation**: Write operations trigger targeted cache clears.
+- **Serialization**: Values are serialized (JSON by default) before storage.
+- **Metrics**: Hit/miss counts, latencies, memory usage via `get_stats()` and CLI.
+
+## Where concepts live in code
+
+- Keys: `yokedcache.utils.generate_cache_key`, `sanitize_key`
+- TTL jitter: `yokedcache.utils.calculate_ttl_with_jitter`
+- Tags: maintained via Redis sets, see `YokedCache._add_tags_to_key`
+- Auto-invalidation: `CachedDatabaseWrapper` in `yokedcache.decorators`
+- Serialization: `yokedcache.utils.serialize_data` / `deserialize_data`
+- Config: `yokedcache.config.CacheConfig`

docs/config-reference.md

@@ -0,0 +1,24 @@
+# Configuration Reference
+
+Key options from `CacheConfig`:
+
+- `redis_url` (str): Redis connection string. Default `redis://localhost:6379/0`.
+- `default_ttl` (int): Default TTL seconds. Default `300`.
+- `key_prefix` (str): Prefix for all keys. Default `yokedcache`.
+- `enable_fuzzy` (bool): Enable fuzzy search. Default `False`.
+- `fuzzy_threshold` (int): 0-100 score cutoff. Default `80`.
+- `max_connections` (int): Redis pool size. Default `50`.
+- `log_level` (str): Logging level. Default `INFO`.
+
+Table-level via `TableCacheConfig`:
+
+- `ttl` (int): Per-table TTL.
+- `tags` (set[str]): Default tags applied to reads.
+- `enable_fuzzy` (bool), `fuzzy_threshold` (int)
+- `serialization_method`: JSON/PICKLE/MSGPACK
+- `query_specific_ttls` (dict[str,int]): per-query-hash TTL overrides.
+
+Env overrides:
+
+- `YOKEDCACHE_REDIS_URL`, `YOKEDCACHE_DEFAULT_TTL`, `YOKEDCACHE_KEY_PREFIX`,
+  `YOKEDCACHE_ENABLE_FUZZY`, `YOKEDCACHE_FUZZY_THRESHOLD`, `YOKEDCACHE_MAX_CONNECTIONS`, `YOKEDCACHE_LOG_LEVEL`.

docs/configuration.md

@@ -0,0 +1,39 @@
+# Configuration
+
+YokedCache can be configured programmatically or via YAML.
+
+## YAML example
+
+```yaml
+# cache_config.yaml
+redis_url: redis://localhost:6379/0
+default_ttl: 300
+key_prefix: yokedcache
+enable_fuzzy: false
+
+tables:
+  users:
+    ttl: 3600
+    tags: ["user_data"]
+    invalidation_rules:
+      - table: users
+        on: [update, delete]
+        invalidate_tags: ["user_data"]
+```
+
+## Programmatic
+
+```python
+from yokedcache import CacheConfig, YokedCache
+
+config = CacheConfig(default_ttl=600, key_prefix="myapp")
+cache = YokedCache(config=config)
+```
+
+## Environment variables
+
+- `YOKEDCACHE_REDIS_URL`
+- `YOKEDCACHE_DEFAULT_TTL`
+- `YOKEDCACHE_KEY_PREFIX`
+- `YOKEDCACHE_ENABLE_FUZZY`
+- `YOKEDCACHE_FUZZY_THRESHOLD`

docs/examples.md

@@ -0,0 +1,26 @@
+# Examples
+
+- Repository examples:
+  - `examples/basic_usage.py`
+  - `examples/fastapi_example.py`
+  - `examples/cache_config.yaml`
+
+## Quick snippets
+
+### Decorator caching
+```python
+from yokedcache import cached
+
+@cached(ttl=600, tags=["products"])  
+async def get_expensive_data(q: str):
+    return expensive_db_query(q)
+```
+
+### Manual operations
+```python
+from yokedcache import YokedCache
+cache = YokedCache()
+await cache.set("key", {"data": 1}, ttl=120, tags=["demo"]) 
+value = await cache.get("key")
+await cache.invalidate_tags(["demo"])  
+```