mkdocs.yml

site_name: djanorm
site_description: A Django-inspired ORM with sync + async support, FastAPI-friendly schemas, and a tiny CLI.
# site_url is read from $SITE_URL so `mkdocs serve` can run at "/" locally
# without forcing the /d-orm/ prefix that GitHub Pages serves under. The
# deploy workflow sets SITE_URL=https://rroblf01.github.io/d-orm/ before
# running mkdocs build, so canonical URLs and the i18n language switcher
# point at the right place in production.
site_url: !ENV [SITE_URL, ""]
repo_url: https://github.com/rroblf01/d-orm/
repo_name: rroblf01/d-orm

theme:
  name: material
  features:
    # navigation.instant is incompatible with the i18n plugin's
    # contextual language switcher — leave it off.
    - navigation.tracking
    - navigation.sections
    - navigation.tabs
    - content.code.copy
    - content.code.annotate
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: deep purple
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: deep purple
      toggle:
        icon: material/weather-night
        name: Switch to light mode

# i18n: docs files use the suffix scheme — `foo.en.md` / `foo.es.md`.
# A language picker appears in the header automatically.
plugins:
  - search
  - i18n:
      docs_structure: suffix
      # API reference pages are English-only (auto-generated from
      # docstrings). Disabling fallback prevents the i18n plugin from
      # duplicating them under /es/, which would make mkdocstrings
      # register every Python identifier twice.
      fallback_to_default: false
      languages:
        - locale: en
          default: true
          name: English
          build: true
        - locale: es
          name: Español
          build: true
          nav_translations:
            Home: Inicio
            Getting started: Empezando
            Tutorial: Tutorial
            Guides: Guías
            Models & fields: Modelos y campos
            Querying: Consultas
            Async patterns: Patrones async
            Migrations: Migraciones
            Online migrations (zero-downtime): Migraciones online (zero-downtime)
            Recursive CTEs (trees): CTEs recursivos (árboles)
            Transactions: Transacciones
            Soft delete: Soft delete
            Audit trail (history): Auditoría (history)
            Row-level multi-tenancy: Multi-tenancy a nivel fila
            FastAPI integration: Integración con FastAPI
            Vector search (pgvector): Búsqueda vectorial (pgvector)
            libsql backend: Backend libsql
            DuckDB backend: Backend DuckDB
            Result cache (Redis): Caché de resultados (Redis)
            CLI reference: Referencia del CLI
            Production deployment: Despliegue en producción
            Cookbook: Recetario
            Troubleshooting: Resolución de problemas
            Migration from Django ORM: Migración desde Django ORM
            When to use what: Cuándo usar qué
            PostgreSQL features: Features PostgreSQL
            Bulk COPY: Bulk COPY
            LISTEN / NOTIFY: LISTEN / NOTIFY
            GIS: GIS
            Advanced PG features: Features avanzadas PG
            Production primitives: Primitivos de producción
            Circuit breaker: Circuit breaker
            Outbox pattern: Patrón outbox
            Idempotency keys: Idempotency keys
            Hash sharding: Sharding por hash
            Lag-aware read routing: Read routing con lag
            Framework-agnostic helpers: Helpers framework-agnósticos
            Release notes: Release notes
            What's new in 4.3: Novedades 4.3
            Upgrading from 4.2 to 4.3: Subiendo de 4.2 a 4.3
            What's new in 4.2: Novedades 4.2
            Upgrading from 4.1 to 4.2: Subiendo de 4.1 a 4.2
            What's new in 4.1: Novedades 4.1
            What's new in 4.0: Novedades 4.0
            Upgrading from 3.3 to 4.0: Subiendo de 3.3 a 4.0
            Sibling packages (mypy / pytest): Paquetes hermanos (mypy / pytest)
            Benchmark vs other ORMs: Benchmark vs otros ORMs
            API Reference: Referencia API
            QuerySet & Manager: QuerySet y Manager
            Signals: Señales
            Pydantic interop: Interop con Pydantic
            pgvector: pgvector
            Connection / health: Conexión y health-check
            Auth (User / Group / tokens): Auth (User / Group / tokens)
            Async-call guard: Async-call guard
            Async-only Model: Modelo async-only
            Task-affinity pool: Pool con afinidad por task
            Field encryption: Cifrado de campos
            Prometheus metrics: Métricas Prometheus
            Observability collectors: Colectores de observabilidad
            Multi-tenant (schema): Multi-tenant (schema)
            Multi-tenant (row): Multi-tenant (fila)
            Cache backends: Backends de caché
            Migration linter: Linter de migraciones
            Query budget: Query budget
            Tree / recursive CTEs: Tree / CTEs recursivos
            Streaming serialisers: Serialisers streaming
            Outbox: Outbox
            Sharding: Sharding
            Idempotency: Idempotency
            Lag-aware router: Router lag-aware
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: false
            show_root_heading: true
            show_signature_annotations: true
            members_order: source
            docstring_style: google
            heading_level: 2

nav:
  - Home: index.md
  - Getting started: getting-started.md
  - Tutorial: tutorial.md
  - Guides:
      - Models & fields: models.md
      - Querying: queries.md
      - Async patterns: async.md
      - Migrations: migrations.md
      - Online migrations (zero-downtime): online-migrations.md
      - Recursive CTEs (trees): recursive-cte.md
      - Transactions: transactions.md
      - Signals: signals.md
      - Soft delete: softdelete.md
      - Audit trail (history): history.md
      - Row-level multi-tenancy: tenants-row.md
      - FastAPI integration: fastapi.md
      - Vector search (pgvector): pgvector.md
      - libsql backend: libsql.md
      - DuckDB backend: duckdb.md
      - Result cache (Redis): cache_redis.md
      - CLI reference: cli.md
      - Production deployment: production.md
      - Cookbook: cookbook.md
      - Troubleshooting: troubleshooting.md
      - Migration from Django ORM: migration-from-django.md
      - When to use what: when-to-use-what.md
  - PostgreSQL features:
      - Bulk COPY: bulk-copy.md
      - LISTEN / NOTIFY: listen-notify.md
      - GIS: gis.md
      - Advanced PG features: advanced.md
  - Production primitives:
      - Circuit breaker: circuit-breaker.md
      - Outbox pattern: outbox.md
      - Idempotency keys: idempotency.md
      - Hash sharding: sharding.md
      - Lag-aware read routing: lag-router.md
      - Framework-agnostic helpers: helpers.md
  - Release notes:
      - What's new in 4.3: v4_3.md
      - Upgrading from 4.2 to 4.3: upgrading-to-4.3.md
      - What's new in 4.2: v4_2.md
      - Upgrading from 4.1 to 4.2: upgrading-to-4.2.md
      - What's new in 4.1: v4_1.md
      - What's new in 4.0: v4_0.md
      - Upgrading from 3.3 to 4.0: upgrading-to-4.0.md
      - Sibling packages (mypy / pytest): sibling-packages.md
      - Benchmark vs other ORMs: bench.md
  - API Reference:
      - Models & fields: api/models.md
      - QuerySet & Manager: api/queryset.md
      - Transactions: api/transaction.md
      - Signals: api/signals.md
      - Pydantic interop: api/pydantic.md
      - pgvector: api/pgvector.md
      - Connection / health: api/connection.md
      - Auth (User / Group / tokens): api/auth.md
      - Async-call guard: api/asyncguard.md
      - Async-only Model: api/asyncmodel.md
      - Task-affinity pool: api/task_pool.md
      - Field encryption: api/encrypted.md
      - Prometheus metrics: api/prometheus.md
      - Observability collectors: api/observability.md
      - Multi-tenant (schema): api/tenants.md
      - Multi-tenant (row): api/tenants_row.md
      - Cache backends: api/cache.md
      - Migration linter: api/migrations_lint.md
      - Query budget: api/budget.md
      - Tree / recursive CTEs: api/tree.md
      - Streaming serialisers: api/streaming.md
      - Bulk COPY: api/bulk_copy.md
      - LISTEN / NOTIFY: api/listen_notify.md
      - GIS: api/gis.md
      - Circuit breaker: api/circuit_breaker.md
      - Outbox: api/outbox.md
      - Sharding: api/sharding.md
      - Idempotency: api/idempotency.md
      - Lag-aware router: api/lag_router.md
      - Audit trail (per-field): api/audit.md
      - GDPR right-to-erasure: api/gdpr.md
      - Materialised views (PG): api/matview.md
      - TimescaleDB helpers: api/timescale.md
      - Outbox CDC publishers: api/outbox_cdc.md
      - Prepared statements (PG): api/prepared_stmts.md
      - Factories (testing): api/factories.md

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - toc:
      permalink: true