Ce que dbt docs generate produit réellement

Lorsque vous exécutez dbt docs generate, dbt produit un site web statique. Comprendre ce que cette commande crée réellement vous aide à prendre des décisions éclairées sur l’hébergement, l’automatisation, et le moment où la limite du frontend par défaut est atteinte.

Les trois fichiers de sortie

La commande produit trois artefacts dans votre répertoire target/ :

1. index.html — L’interface frontend. Il s’agit d’une application monopage (SPA) qui effectue tout le rendu côté client. dbt copie ce fichier depuis ses templates internes ; vous ne l’écrivez ni ne le modifiez.

2. manifest.json — Les métadonnées compilées de votre projet. Modèles, sources, tests, macros, expositions et leurs relations. Le champ compiled_code apparaît ici, montrant le SQL entièrement rendu pour chaque modèle après le traitement Jinja. C’est le même manifest qui alimente dbt ls, dbt run --select, et toutes les autres commandes d’introspection de projet.

3. catalog.json — Les métadonnées de la base de données. Types de colonnes, nombres de lignes, statistiques des tables. C’est le seul artefact qui nécessite une connexion à la base de données active, car dbt interroge l’INFORMATION_SCHEMA de votre entrepôt (ou équivalent) pour le construire.

Ensemble, l’interface HTML charge les deux fichiers JSON et effectue le rendu du site de documentation entièrement dans le navigateur. Il n’y a pas de traitement côté serveur après l’étape de génération initiale.

Les flags importants

--select

Limite la génération du catalogue à des nœuds spécifiques :

dbt docs generate --select marts.*

Pour les grands projets, cela accélère considérablement la génération. Le manifest est toujours complet (il reflète l’ensemble de votre projet), mais le catalogue ne comprend les métadonnées que pour les modèles sélectionnés. Les modèles non sélectionnés apparaissent toujours dans le site de documentation mais sans les détails au niveau des colonnes.

--no-compile

Ignore la recompilation si votre manifest est déjà à jour :

dbt docs generate --no-compile

Utile dans les pipelines CI où vous avez déjà exécuté dbt compile ou dbt run plus tôt dans le même job. Le manifest de cette étape est réutilisé, économisant le temps de compilation.

--static

C’est le flag le plus déterminant pour le déploiement :

dbt docs generate --static

Sans --static, vous obtenez trois fichiers séparés qui nécessitent un serveur web capable de servir le JSON aux côtés du HTML. La SPA effectue des requêtes pour charger manifest.json et catalog.json au moment de l’exécution.

Avec --static, dbt produit un seul fichier static_index.html avec les deux charges JSON intégrées inline. Ce fichier est complètement autonome. Vous pouvez l’ouvrir directement dans un navigateur, l’héberger sur n’importe quel serveur de fichiers statiques, ou l’envoyer en pièce jointe (bien qu’à grande échelle, il puisse être très volumineux).

Pour le déploiement vers GitHub Pages, Netlify, ou le stockage cloud, le flag --static simplifie l’hébergement car vous n’avez besoin de servir qu’un seul fichier. La contrepartie est la taille du fichier : un projet avec un manifest et un catalogue volumineux produit un static_index.html qui peut peser des dizaines de mégaoctets.

dbt docs serve est un outil de prévisualisation

dbt docs serve --port 8080

Cela démarre un serveur web local pour prévisualiser le site généré. La documentation officielle de dbt indique explicitement que dbt docs serve n’est pas destiné à un usage en production. C’est une commodité de développement, pas une stratégie de déploiement.

Le serveur n’a pas d’authentification, pas de cache, pas de TLS, et pas de gestion de la concurrence. Il sert les fichiers depuis votre répertoire target/ directement. Pour tout ce qui va au-delà de « je veux vérifier l’aspect de ma documentation en ce moment », vous avez besoin d’une solution d’hébergement appropriée.

Comment la génération s’intègre dans un pipeline

Un pipeline de documentation typique exécute ces étapes :

1. dbt run (ou dbt build) — matérialise les modèles, produisant manifest.json
2. dbt docs generate — interroge la base de données pour les métadonnées du catalogue, produit catalog.json et index.html
3. Déployer le contenu de target/ (ou static_index.html) sur votre plateforme d’hébergement

L’étape 2 nécessite un accès à la base de données car elle interroge les métadonnées de l’entrepôt. Si vous exécutez la génération de documentation en CI, votre environnement CI a besoin de credentials avec au moins un accès en lecture aux schémas dans lesquels vos modèles se matérialisent. Le flag --select peut limiter les schémas interrogés si le compte de service CI a des permissions restreintes.

Pour le déploiement automatisé, ce pipeline s’exécute généralement à la fusion vers main, garantissant que la documentation hébergée reflète toujours l’état de production le plus récent de votre projet.