Personnalisation et déploiement de la documentation dbt

Ce hub couvre le déploiement de la documentation dbt au-delà de localhost — de la compréhension de ce que produit dbt docs generate au choix d’une plateforme d’hébergement, à l’automatisation du déploiement, et à la décision de remplacer entièrement le site par défaut.

Prérequis

• Un projet dbt (Core ou Cloud) avec des modèles
• Familiarité avec dbt docs generate et dbt docs serve
• Pour les notes sur l’hébergement : accès à au moins l’un de GitHub, GCP, AWS ou un runtime de containers

Ordre de lecture

Les notes suivent la progression naturelle du déploiement de la documentation dbt :

1. Artefacts générés par dbt docs — Commencez ici. Comprenez ce que dbt docs generate produit réellement : les trois fichiers de sortie, les flags qui contrôlent la génération (--static, --select, --no-compile), et pourquoi dbt docs serve est un outil de prévisualisation, pas une stratégie de déploiement.

2. Options de personnalisation du site dbt docs — Avant de déployer, rendez le site digne d’être visité. Le doc block __overview__, les couleurs des nœuds du DAG et le masquage des modèles parasites sont les trois personnalisations disponibles. Cette note couvre aussi où se terminent les options de personnalisation, plus tôt qu’on ne pourrait le croire.

3. Performances de dbt docs à grande échelle — Le frontend par défaut est une SPA AngularJS 1.x qui parse tout côté client. Pour les petits projets, c’est correct. Pour les grands (500+ modèles), cela devient un vrai problème. Comprenez le plafond de performance avant d’investir dans l’hébergement.

4. Hébergement de dbt docs au-delà de localhost — Le guide de référence des options de déploiement : GitHub Pages, Netlify, GCS avec IAP, S3 avec CloudFront, et Docker avec Nginx. Organisé par complexité, avec les considérations d’authentification pour chacun.

5. Automatisation du déploiement de dbt docs — Workflows CI/CD pour GitHub Actions et GitLab CI, opérateurs Astronomer Cosmos pour Airflow, et patterns pour pousser la documentation vers des plateformes non techniques comme Notion.

6. Alternatives à la documentation dbt par défaut — Quand la personnalisation et les optimisations d’hébergement ne peuvent pas corriger les limitations sous-jacentes. Le frontend Next.js de remplacement de Dagster, dbterd pour la génération d’ERD, les catalogues de données et dbt Cloud Catalog. Inclut un cadre de décision pour choisir entre eux.

Lecture complémentaire

Pour la partie contenu de la documentation dbt (quoi écrire, pas où l’héberger), voir le hub de documentation dbt assistée par IA, les doc blocks et les capacités Markdown. Pour pousser les descriptions dans l’entrepôt plutôt que (ou en parallèle de) le site de documentation, voir persist_docs.