Add comprehensive MkDocs documentation for wrappers and adapters (#128)

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: William Easton <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: strawgate <[email protected]>

Author: 3 people

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install documentation dependencies
+        run: uv pip install --system mkdocs mkdocs-material 'mkdocstrings[python]' mkdocstrings-python
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

.markdownlint.jsonc

@@ -5,5 +5,8 @@
     "line_length": 80,
     "code_blocks": false, // Don't restrict line length in code blocks
     "tables": false // Don't restrict line length in tables
+  },
+  "MD024": {
+    "siblings_only": true // Allow duplicate headings in different sections
   }
 }

Makefile

@@ -1,5 +1,5 @@
 .PHONY: bump-version bump-version-dry codegen lint typecheck sync precommit test build help
-.PHONY: install test-aio test-sync test-shared
+.PHONY: install test-aio test-sync test-shared docs-serve docs-build docs-deploy
 
 # Default target - show help
 .DEFAULT_GOAL := help
@@ -19,6 +19,9 @@ help:
 	@echo "  make build             - Build all packages"
 	@echo "  make codegen           - Generate sync package from async"
 	@echo "  make precommit         - Run pre-commit checks (lint + typecheck + codegen)"
+	@echo "  make docs-serve        - Start documentation server"
+	@echo "  make docs-build        - Build documentation"
+	@echo "  make docs-deploy       - Deploy documentation to GitHub Pages"
 	@echo ""
 	@echo "Per-project targets (use PROJECT=<path>):"
 	@echo "  make sync PROJECT=key-value/key-value-aio"
@@ -119,4 +122,17 @@ else
 	@cd key-value/key-value-shared && uv build .
 endif
 
-precommit: lint codegen lint typecheck 
+precommit: lint codegen lint typecheck
+
+# Documentation targets
+docs-serve:
+	@echo "Starting documentation server..."
+	@uv run --extra docs mkdocs serve
+
+docs-build:
+	@echo "Building documentation..."
+	@uv run --extra docs mkdocs build
+
+docs-deploy:
+	@echo "Deploying documentation to GitHub Pages..."
+	@uv run --extra docs mkdocs gh-deploy --force

README.md

@@ -6,6 +6,14 @@ This monorepo contains two libraries:
 - `py-key-value-sync`: Sync key-value store library (under development;
   generated from the async API).
 
+## Documentation
+
+- [Full Documentation](https://strawgate.github.io/py-key-value/)
+- [Getting Started Guide](https://strawgate.github.io/py-key-value/getting-started/)
+- [Wrappers Guide](https://strawgate.github.io/py-key-value/wrappers/)
+- [Adapters Guide](https://strawgate.github.io/py-key-value/adapters/)
+- [API Reference](https://strawgate.github.io/py-key-value/api/protocols/)
+
 ## Why use this library?
 
 - **Multiple backends**: DynamoDB, Elasticsearch, Memcached, MongoDB, Redis,