doc

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**", "mkdocs.yml", "pyproject.toml", "uv.lock"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install docs dependencies
+        run: uv sync --group docs
+
+      - name: Build with mkdocs
+        run: uv run mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -46,6 +46,9 @@ htmlcov/
 # ruff
 .ruff_cache/
 
+# Docs
+site/
+
 # Database
 *.db
 *.sqlite

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install api consume mcp test lint lint-fix typecheck check migrate migrate-create clean
+.PHONY: help install api consume mcp test lint lint-fix typecheck check migrate migrate-create docs docs-serve clean
 
 help: ## Show this help message
 	@echo "Available commands:"
@@ -38,6 +38,12 @@ migrate: ## Run database migrations
 migrate-create: ## Create new migration (usage: make migrate-create MSG="description")
 	uv run alembic revision --autogenerate -m "$(MSG)"
 
+docs: ## Build the documentation site
+	uv run mkdocs build
+
+docs-serve: ## Serve documentation locally (http://localhost:9000)
+	uv run mkdocs serve -a localhost:9000
+
 clean: ## Remove caches and build artifacts
 	find . -type d -name "__pycache__" -exec rm -rf {} +
 	find . -type d -name ".pytest_cache" -exec rm -rf {} +