Documentation

Plugin Living Documentation
Diagrammes, fichiers et topologie des modules.

Référence complète du plugin Living Documentation HexaGlue : options de configuration, fichiers générés, diagrammes et support multi-module.

Installation

Ajouter le plugin Living Documentation

<plugin>
    <groupId>io.hexaglue</groupId>
    <artifactId>hexaglue-maven-plugin</artifactId>
    <version>6.0.0</version>
    <extensions>true</extensions>
    <configuration>
        <basePackage>com.acme.shop</basePackage>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>io.hexaglue.plugins</groupId>
            <artifactId>hexaglue-plugin-living-doc</artifactId>
            <version>3.0.0</version>
        </dependency>
    </dependencies>
</plugin>

La documentation est générée automatiquement lors de la phase generate-sources (mvn compile). Les fichiers sont écrits dans target/hexaglue/reports/{outputDir}/.

Trois éléments clés dans cette configuration :

<extensions>true</extensions> : active le binding automatique aux phases Maven. Les goals HexaGlue se déclenchent sans configuration supplémentaire lors de mvn compile.
<basePackage> : package racine à analyser. Seules les classes de ce package et de ses sous-packages sont classifiées par HexaGlue.
Le plugin Living Documentation est déclaré comme <dependency> du plugin Maven, pas du projet. HexaGlue découvre automatiquement les plugins via le mécanisme Java ServiceLoader : il suffit de les ajouter ici pour qu'ils soient actifs.

Les projets utilisant Lombok sont pris en charge nativement depuis HexaGlue 6.0.0 : le delombok est injecté automatiquement avant l'analyse, aucune configuration spéciale n'est nécessaire côté plugin.

Configuration

Paramètres Maven

La configuration de la génération se fait via les paramètres <configuration> du plugin Maven dans le pom.xml.
Ces paramètres contrôlent le package analysé, le comportement de validation et la gestion des fichiers obsolètes.
Le paramètre skip peut aussi être passé en ligne de commande via -Dhexaglue.skip=true.

Option	Défaut	Description
`basePackage`	(requis)	Package racine à analyser. La documentation est générée à partir des types de domaine de ce package.
`outputDirectory`	`target/hexaglue/generated-sources`	Répertoire de base pour les fichiers générés
`skip`	`false`	Désactive complètement l'exécution de HexaGlue (configurable via `-Dhexaglue.skip=true`)
`skipValidation`	`false`	Ignore la validation des classifications avant la génération de la documentation
`failOnUnclassified`	`false`	Fait échouer le build si des types du domaine ne peuvent pas être classifiés
`tolerantResolution`	`false`	Active la résolution tolérante des types non résolus. Utile pour les projets utilisant des annotation processors (MapStruct, Immutables) dont le code généré n'est pas encore sur le classpath (configurable via `-Dhexaglue.tolerantResolution=true`)

Configuration

Options YAML

Le fichier hexaglue.yaml, placé à la racine du projet (à côté du pom.xml), centralise la configuration de HexaGlue et de tous ses plugins.
Les options ci-dessous se configurent dans la section plugins.io.hexaglue.plugin.livingdoc: du fichier YAML.
Les paramètres Maven (<configuration>) sont prioritaires sur les valeurs YAML.

Option	Type	Défaut	Description
`outputDir`	string	`"living-doc"`	Répertoire de sortie pour les fichiers de documentation (relatif à `target/hexaglue/reports/`)
`generateDiagrams`	boolean	`true`	Active la génération de diagrammes Mermaid dans un fichier `diagrams.md` dédié
`maxPropertiesInDiagram`	integer	`5`	Nombre maximum de propriétés affichées par classe dans les diagrammes
`includeDebugSections`	boolean	`true`	Inclut les sections de debug (classification trace, source location) dans `domain.md` et `ports.md`. Mettre à `false` pour une documentation plus concise.
`outputDirectory`	string	(défaut global)	Répertoire de sortie spécifique au plugin, surchargeant le répertoire global

plugins:
  io.hexaglue.plugin.livingdoc:
    outputDir: "living-doc"
    generateDiagrams: true
    maxPropertiesInDiagram: 5
    includeDebugSections: true

Sortie

Structure des fichiers générés

Le plugin génère 4 à 5 fichiers Markdown selon la configuration et le type de projet (mono ou multi-module).

Fichier	Contenu	Condition
`README.md`	Vue d'ensemble : métriques, résumé du domaine, résumé des ports, contextes bornés, glossaire, arbre de packages, index des types	Toujours généré
`domain.md`	Modèle de domaine détaillé : agrégats (avec entités, VO, identifiants), services, événements, relations architecturales	Toujours généré
`ports.md`	Documentation des ports : ports driving (entrants) et driven (sortants) avec signatures des méthodes et types	Toujours généré
`diagrams.md`	Diagrammes Mermaid : modèle de domaine (classes), agrégats individuels, flux hexagonal, graphe de dépendances	Seulement si `generateDiagrams: true`
`modules.md`	Topologie des modules : tableau récapitulatif (rôles, comptages), inventaire détaillé des types par module	Seulement en multi-module

Living documentation HexaGlue : agrégat Account avec identity details, properties (id, ownerName, balance, transactions) et niveau de confiance — Exemple de sortie : agrégat Account avec identity, properties et niveau de confiance

Vue d'ensemble

Ce que contient le fichier principal

Le README.md est le point d'entrée de la documentation. Il donne une vue synthétique de l'architecture.

Living documentation HexaGlue : README.md généré avec table des matières, tableau récapitulatif des types et liens vers domain.md, ports.md, diagrams.md — README.md généré : table des matières, métriques et liens de navigation

Tableau récapitulatif : comptage des agrégats, entités, value objects, identifiants, services applicatifs, ports driving et driven
Liens de navigation : vers domain.md, ports.md, diagrams.md, modules.md
Diagramme d'architecture : diagramme Mermaid de vue d'ensemble (si diagrammes activés)
Résumé du domaine : tableaux des agrégats, value objects, identifiants
Résumé des ports : tableaux des ports driving et driven
Contextes bornés : analyse de la structure des packages (si détectés)
Topologie des modules : rôles et distribution des types par module (si multi-module)
Glossaire : terminologie du domaine avec types et packages
Arbre des packages : visualisation de l'arborescence
Index : index alphabétique des types avec références croisées

Diagrammes

4 types de diagrammes générés

Les diagrammes sont au format Mermaid, directement lisibles sur GitHub, GitLab et la plupart des outils de documentation.

Diagramme de classes du domaine

Tous les types du domaine avec leurs propriétés (limitées à maxPropertiesInDiagram) et leurs relations.

Diagrammes d'agrégats

Un diagramme par agrégat montrant la racine, les entités et les value objects associés.

Flux hexagonal

Diagramme montrant les interactions entre ports driving, services applicatifs, ports driven et adapters.

Graphe de dépendances

Graphe orienté des dépendances entre types, montrant la direction vers le domaine.

Multi-module

Topologie des modules

En multi-module, le plugin génère un fichier modules.md supplémentaire et ajoute une section topologie dans le README.md.

Ce que contient `modules.md`

Tableau récapitulatif : pour chaque module, son identifiant, son rôle (DOMAIN, INFRASTRUCTURE, APPLICATION, API, ASSEMBLY, SHARED), le nombre de types et le package de base
Sections par module : inventaire détaillé de tous les types classifiés dans chaque module, organisés par rôle architectural

Le code change. La documentation aussi.
Générez-la à chaque build.

Voyez la documentation générée sur un projet réel ou explorez toutes les options du plugin.

Voir la documentation en action Se faire accompagner

Plugin Living DocumentationDiagrammes, fichiers et topologie des modules.