Automatiser le déploiement de la documentation dbt

Exécuter dbt docs generate manuellement et déployer la sortie produit une documentation périmée. Automatiser le déploiement garantit que la documentation reste à jour à mesure que les modèles évoluent.

Le pattern de base

Quelle que soit la plateforme d’hébergement, le pattern d’automatisation est identique :

1. Déclencheur : fusion vers main (ou fin d’une exécution dbt en production)
2. Génération : dbt docs generate (avec --static si votre hôte prend en charge le service de fichier unique)
3. Déploiement : pousser la sortie vers la plateforme d’hébergement

Le choix du déclencheur est important. Fusionner vers main capture les changements de schéma et de documentation. Déclencher après une exécution dbt run en production capture les changements de catalogue (nouvelles colonnes, nombre de lignes mis à jour). L’idéal est de faire les deux : générer à la fusion pour des mises à jour rapides, et régénérer selon un calendrier pour maintenir les métadonnées du catalogue à jour.

Workflows CI/CD

GitHub Actions

L’implémentation la plus simple pour les équipes sur GitHub :

name: Deploy dbt docs
on:
  push:
    branches: [main]

jobs:
  deploy-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dbt
        run: pip install dbt-bigquery  # ou votre adaptateur
      - name: Generate docs
        run: dbt docs generate --static
        env:
          DBT_PROFILES_DIR: .
      - name: Deploy to Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./target

Pour d’autres cibles d’hébergement, remplacez l’étape de déploiement :

# Netlify
- name: Deploy to Netlify
  run: npx netlify-cli deploy --prod --dir=target
  env:
    NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
    NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

# GCS
- name: Deploy to GCS
  run: gsutil -m rsync -r target/ gs://your-docs-bucket/

GitLab CI

deploy-docs:
  stage: deploy
  script:
    - pip install dbt-bigquery
    - dbt docs generate --static
  artifacts:
    paths:
      - target/
  pages:
    stage: deploy
    script:
      - mv target public
    artifacts:
      paths:
        - public

Astronomer Cosmos pour Airflow

Si votre projet dbt s’exécute sur Airflow, Astronomer Cosmos fournit des opérateurs préconstruits qui génèrent et envoient la documentation en une seule tâche Airflow :

• DbtDocsS3Operator — génère la documentation et l’envoie vers S3
• DbtDocsGCSOperator — génère la documentation et l’envoie vers GCS
• DbtDocsAzureStorageOperator — génère la documentation et l’envoie vers Azure Blob Storage

Ces opérateurs prennent en charge le flag --static et gèrent l’étape d’envoi. Le pattern typique ajoute une tâche de génération de documentation à la fin de votre DAG dbt :

from cosmos.operators.airflow_async import DbtDocsGCSOperator

generate_docs = DbtDocsGCSOperator(
    task_id="generate_and_upload_docs",
    project_dir="/path/to/dbt/project",
    conn_id="gcp_conn",
    bucket_name="your-docs-bucket",
    static=True,
)

# Chaîner après les tâches dbt run
dbt_run >> generate_docs

Cela garantit que la documentation est régénérée à chaque exécution du pipeline dbt en production, maintenant les métadonnées du catalogue (nombres de lignes, types de colonnes) à jour.

Pousser la documentation vers des plateformes non techniques

Pour les équipes dont l’audience principale de la documentation est non technique, le site dbt docs standard n’est peut-être pas la bonne destination. dbt-docs-to-notion exporte la documentation des modèles vers une base de données Notion :

• Chaque modèle obtient sa propre page Notion
• Les descriptions, colonnes et tests sont structurés comme des propriétés Notion
• L’export peut s’exécuter selon un calendrier pour maintenir Notion synchronisé

Cela ne remplace pas le site de documentation complet pour les ingénieurs qui ont besoin des vues DAG et de lignage. Mais cela rend les métadonnées des modèles accessibles aux personnes qui vivent dans Notion — chefs de produit, analystes, parties prenantes métier qui n’ouvriront jamais un site de documentation technique.

Considérations de planification

À quelle fréquence la documentation doit-elle être régénérée ? La réponse dépend de ce qui change :

Si vos exécutions dbt en production ont lieu quotidiennement, régénérer la documentation quotidiennement capture à la fois les changements de schéma et de catalogue. Si vous fusionnez fréquemment mais exécutez la production moins souvent, déclencher à la fusion donne des mises à jour de documentation plus rapides tandis qu’une régénération planifiée maintient les métadonnées du catalogue à jour.

Pour la plupart des équipes, déclencher à la fusion vers main est suffisant. Les métadonnées du catalogue (nombres de lignes, types de colonnes exacts) sont moins critiques que des descriptions de modèles précises et un lignage à jour. Si la fraîcheur des données du catalogue est importante pour votre équipe, ajoutez une régénération planifiée après la fin de votre exécution en production.

Le signal de fraîcheur

Un pattern utile à adopter : inclure un indicateur de fraîcheur dans votre page d’aperçu. Un horodatage de génération dans le bloc doc __overview__ indique aux visiteurs à quel point la documentation est récente :

{% docs __overview__ %}
# Documentation de la plateforme de données

Dernière génération : {{ run_started_at.strftime('%Y-%m-%d %H:%M UTC') }}

...
{% enddocs %}

Ce Jinja est résolu au moment de dbt docs generate. Les visiteurs peuvent immédiatement voir si la documentation reflète l’état actuel ou celui du mois dernier. Si l’horodatage est ancien, c’est un signal que votre pipeline d’automatisation nécessite une attention.