docs: add MkDocs Material site with versioned GitHub Pages deployment

.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: Docs
+
+# NOTE: The gh-pages branch must exist and GitHub Pages must be enabled in
+# repo Settings → Pages → Source: Deploy from branch `gh-pages`.
+
+on:
+  push:
+    tags:
+      - "v*"
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to deploy (e.g. 0.4.0)"
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup UV
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Configure git identity
+        run: |
+          git config --global user.name "github-actions"
+          git config --global user.email "github-actions@github.com"
+
+      - name: Resolve version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            raw="${{ github.event.inputs.version }}"
+          elif [ "${{ github.ref_type }}" = "tag" ]; then
+            raw="${{ github.ref_name }}"
+          else
+            raw="$(uv run python -m semantic_release version --print-last-released)"
+          fi
+          echo "value=${raw#v}" >> $GITHUB_OUTPUT
+
+      - name: Deploy docs
+        run: uv run mike deploy --push --update-aliases ${{ steps.version.outputs.value }} latest

docs/index.md

@@ -0,0 +1,40 @@
+# python-seedwork
+
+[![PyPI version](https://img.shields.io/pypi/v/python-seedwork)](https://pypi.org/project/python-seedwork/)
+[![Python](https://img.shields.io/pypi/pyversions/python-seedwork)](https://pypi.org/project/python-seedwork/)
+[![License: MIT](https://img.shields.io/pypi/l/python-seedwork)](https://github.com/aseguragonzalez/python-seedwork/blob/main/LICENSE)
+[![CI](https://github.com/aseguragonzalez/python-seedwork/actions/workflows/ci.yml/badge.svg)](https://github.com/aseguragonzalez/python-seedwork/actions/workflows/ci.yml)
+
+DDD and Hexagonal Architecture building blocks for Python.
+
+## Goals
+
+- **Unify design patterns.** Provide a shared vocabulary — entities, aggregates, value objects, domain events, CQRS buses — so every bounded context starts from the same foundation.
+- **Keep domain logic pure.** The domain layer has zero framework or infrastructure imports. Business rules live in the domain; everything else lives in infrastructure.
+- **Clear layer boundaries.** Protocols define contracts; implementations satisfy them structurally. The dependency direction is enforced: domain ← application ← infrastructure.
+
+## Components
+
+| Layer | Package | Components |
+|---|---|---|
+| Domain | `seedwork.domain` | `Entity`, `AggregateRoot`, `ValueObject`, `DomainEvent`, `DomainEventRecord`, `DomainError`, `Repository`, `UnitOfWork` |
+| Application | `seedwork.application` | `Command`, `Query[TResult]`, `CommandHandler`, `QueryHandler`, `CommandBus`, `QueryBus`, `Result`, `DomainEventBusPublisher`, `DomainEventBusSubscriber`, `DomainEventBus`, `DomainEventHandler`, `BaseIntegrationEvent`, `IntegrationEvent`, `IntegrationEventPublisher`, `IntegrationEventHandler`, `BackgroundTask`, `TaskScheduler` |
+| Infrastructure | `seedwork.infrastructure` | `RegistryCommandBus`, `RegistryQueryBus`, `TransactionalCommandBus`, `DomainEventCoordinatorCommandBus`, `CommandBusBuilder`, `QueryBusBuilder`, `DeferredDomainEventBus`, `DomainEventPublishingRepository`, `InMemoryRepository` |
+
+All components are re-exported from the top-level `seedwork` package.
+
+## Installation
+
+```bash
+pip install python-seedwork
+```
+
+Requires Python 3.12+. Ships a `py.typed` marker (PEP 561) — mypy and pyright pick up the inline types automatically.
+
+## Documentation
+
+- [Getting Started](getting-started.md) — Step-by-step guide: install, define a domain model, handle commands, wire buses.
+- [Component Reference](component-reference.md) — Every abstract class, protocol, and infrastructure component.
+- [Architecture](architecture.md) — Service building blocks: API, database, subscriber, publisher, worker, outbox, observability.
+- [Best Practices](best-practices.md) — Design rules for domain components, application layer contracts, and event/task selection.
+- [Coding Standards](coding-standards.md) — Conventions aligned with DDD and Clean Architecture, with do/don't guidelines.

docs/javascripts/mermaid.js

@@ -0,0 +1,4 @@
+document$.subscribe(({ body }) => {
+  mermaid.initialize({ startOnLoad: false })
+  mermaid.run({ nodes: body.querySelectorAll(".mermaid") })
+})

mkdocs.yml

@@ -0,0 +1,40 @@
+site_name: python-seedwork
+site_url: https://aseguragonzalez.github.io/python-seedwork/
+repo_url: https://github.com/aseguragonzalez/python-seedwork
+repo_name: aseguragonzalez/python-seedwork
+
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.top
+    - content.code.annotate
+    - content.code.copy
+
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+extra_javascript:
+  - javascripts/mermaid.js
+  - https://unpkg.com/mermaid@11/dist/mermaid.min.js
+
+plugins:
+  - search
+  - mike:
+      version_selector: true
+
+extra:
+  version:
+    provider: mike
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Component Reference: component-reference.md
+  - Architecture: architecture.md
+  - Best Practices: best-practices.md
+  - Coding Standards: coding-standards.md

pyproject.toml

@@ -103,5 +103,7 @@ dev = [
     "hatch>=1.13",
     "python-semantic-release>=9.0",
     "pre-commit>=4.0",
+    "mkdocs-material>=9.5",
+    "mike>=2.0",
 ]