b552a1745b
Étapes 1 et 3 du chantier de documentation.
DIX NUMÉROS RETIRÉS — ECS-100/101/102/300/301/304/400/402/403/404. Ils
n'existaient QUE comme une étiquette de trois mots dans une table de statut :
aucun énoncé, nulle part. Leur reconstruire un texte depuis l'étiquette et le
code aurait été inventer une exigence en croyant la restituer, et une règle
inventée qui porte un numéro fait autorité pour toujours. Si le texte d'origine
n'existe nulle part, la règle n'existe pas ; ce que le code fait reste vrai, il
n'a simplement plus de règle à citer.
Retirés, pas effacés : tools/rules-retired.txt les porte, l'index les publie avec
leur date, leur motif et les endroits qui les citent encore. Un identifiant
croisé dans un vieux relevé renvoie donc à quelque chose — RELEVE_ECS306.md cite
toujours ECS-404, et c'est bien. Un numéro retiré n'est JAMAIS réattribué : le
générateur refuse une définition qui en reprendrait un, une même référence ne
doit pas désigner deux exigences selon la date de lecture.
Les citations VIVANTES de ces numéros sont retirées (spec_ecs §2/§4/§5,
AGENTS.md) — les phrases tiennent sans elles. Les citations HISTORIQUES restent.
DEUX TABLES SUPPRIMÉES, pas corrigées. §1 déclarait ECS-410/411/412 « absents »
alors que les trois étaient implémentées et testées. §9 « Traçabilité » nommait
HUIT tests qui n'ont jamais été écrits. Son défaut n'était pas d'être périmée
mais de mélanger un CONSTAT et une INTENTION sous la même colonne — « ECS-306 →
testEcsBudgetUnderLock » est un fait, « ECS-303 → banc » est un projet ; réunis,
le second garantit que l'ensemble devient faux. Les deux sont séparés : le
constat est généré, l'intention devient « Ce qui reste à éprouver », avec pour
chaque exigence POURQUOI elle n'est pas éprouvée.
DOXYGEN (étape 3). doc-generated/RULES.md entre en INPUT — ses ancres {#LM-1105}
rendent \rule{} résoluble — et l'alias \rule{1} est défini. Les specs restent
HORS périmètre : les y ajouter ferait entrer deux fois le même énoncé et
doublerait les ancres. Les 250 citations existantes ne sont pas converties : le
générateur les voit déjà, et \ref sert l'autre sens — du commentaire vers la
règle. Éprouvé sur un cas réel, \rule{LM-1209-c} résout sans avertissement.
Piège d'ordonnancement corrigé au passage : gen-rules.py écrit DANS $SORTIE, donc
l'appeler avant `rm -rf "$SORTIE"` l'effaçait aussitôt — doxygen signalait
« RULES.md is not a readable file ». L'index se produit après le nettoyage. Son
code de retour ne stoppe pas la génération (un index incomplet reste utile à
lire) mais est répercuté à la fin.
Avertissements doxygen : 30 → 26, dont 3 étaient les miens — rankOrigin(),
setRankOrigin() et knownRankOrigins() n'étaient pas documentés (DoD 5).
L'index sort désormais RC=0 : 111 règles, aucun orphelin, aucun domicile ambigu.
69 spécifiées seules, 16 citées par un test, 14 par le code, 12 vérifiées sur
machine. Build 0/0, loadmodel 20/20.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015F7G5VeaPVSMeVNjiGj36p
110 lines
4.5 KiB
Bash
Executable File
110 lines
4.5 KiB
Bash
Executable File
#!/bin/bash
|
|
# SPDX-License-Identifier: GPL-3.0-or-later
|
|
# Copyright (C) 2025 - 2026, Patrick Schurig / ETM PowerSync
|
|
#
|
|
# Génération reproductible de la documentation — UNE seule commande, le Doxyfile
|
|
# du dépôt, épinglé.
|
|
#
|
|
# ./tools/gen-doc.sh
|
|
#
|
|
# Pourquoi une commande unique plutôt qu'un « doxygen » lancé à la main : le
|
|
# nombre d'avertissements NE VEUT RIEN DIRE hors de sa configuration exacte. Le
|
|
# piège a déjà été rencontré — 163 avertissements sans générateur de sortie
|
|
# contre 113 avec HTML+XML, sur le même arbre. Un chiffre de référence ne se
|
|
# compare qu'à un chiffre produit de la même façon ; ce script est cette façon.
|
|
#
|
|
# DÉPENDANCES — de la CIBLE DOC uniquement, jamais du build du paquet :
|
|
# apt install doxygen graphviz
|
|
# Le conteneur build-cross-arm64 n'a rien à faire de Graphviz : il compile, il
|
|
# ne dessine pas.
|
|
|
|
set -u
|
|
|
|
RACINE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
|
DOXYFILE="$RACINE/Doxyfile"
|
|
SORTIE="$RACINE/doc-generated"
|
|
VERSION_ATTENDUE="1.9.8"
|
|
|
|
cd "$RACINE" || exit 1
|
|
|
|
manquant=0
|
|
for outil in doxygen dot; do
|
|
if ! command -v "$outil" >/dev/null 2>&1; then
|
|
echo "MANQUANT : $outil" >&2
|
|
manquant=1
|
|
fi
|
|
done
|
|
if [ "$manquant" -ne 0 ]; then
|
|
echo "" >&2
|
|
echo "Dépendances de la cible doc : apt install doxygen graphviz" >&2
|
|
exit 127
|
|
fi
|
|
|
|
# L'INDEX DES RÈGLES d'abord : le Doxyfile le prend en entrée, et ses ancres {#LM-1105}
|
|
# sont ce qui rend \rule{} résoluble. Un index absent produirait des \ref cassés en masse,
|
|
# donc un compte d'avertissements incomparable — exactement ce que ce script existe pour
|
|
# empêcher.
|
|
#
|
|
# Son code de retour ne STOPPE pas la génération : un index incomplet reste utile à lire,
|
|
# et refuser de produire la doc parce qu'une règle manque punirait le mauvais geste. Il est
|
|
# répercuté à la fin, pour que l'appelant — un humain ou la CI — le voie.
|
|
VERSION_REELLE="$(doxygen --version | cut -d' ' -f1)"
|
|
if [ "$VERSION_REELLE" != "$VERSION_ATTENDUE" ]; then
|
|
# Avertissement et non erreur : la génération reste utile, mais le compte
|
|
# d'avertissements n'est plus comparable au chiffre de référence.
|
|
echo "ATTENTION : doxygen $VERSION_REELLE, référence établie sous $VERSION_ATTENDUE." >&2
|
|
echo " Les graphes restent valables ; le COMPTE d'avertissements," >&2
|
|
echo " lui, n'est pas comparable d'une version à l'autre." >&2
|
|
fi
|
|
|
|
rm -rf "$SORTIE"
|
|
|
|
# L'INDEX DES RÈGLES, et il se produit APRÈS le nettoyage — il vit DANS $SORTIE, donc le
|
|
# générer avant reviendrait à l'effacer aussitôt. Doxygen le prend en entrée : ses ancres
|
|
# {#LM-1105} sont ce qui rend \rule{} résoluble, et un index absent produirait des \ref
|
|
# cassés en masse, donc un compte d'avertissements incomparable — exactement ce que ce
|
|
# script existe pour empêcher.
|
|
#
|
|
# Son code de retour ne STOPPE pas la génération : un index incomplet reste utile à lire, et
|
|
# refuser de produire la doc parce qu'une règle manque punirait le mauvais geste. Il est
|
|
# répercuté à la fin, pour que l'appelant — humain ou CI — le voie.
|
|
echo "→ index des règles"
|
|
python3 "$RACINE/tools/gen-rules.py"
|
|
RC_REGLES=$?
|
|
JOURNAL="$(mktemp)"
|
|
trap 'rm -f "$JOURNAL"' EXIT
|
|
|
|
doxygen "$DOXYFILE" 2>"$JOURNAL"
|
|
code=$?
|
|
|
|
# Le Doxyfile écrit déjà ses avertissements dans WARN_LOGFILE ; on compte ici ce
|
|
# qui est réellement remonté, quelle que soit la destination.
|
|
LOGFILE="$(sed -n 's/^WARN_LOGFILE *= *//p' "$DOXYFILE" | tr -d ' ')"
|
|
if [ -n "$LOGFILE" ] && [ -f "$RACINE/$LOGFILE" ]; then
|
|
JOURNAL_EFFECTIF="$RACINE/$LOGFILE"
|
|
else
|
|
JOURNAL_EFFECTIF="$JOURNAL"
|
|
fi
|
|
AVERTISSEMENTS="$(grep -c -i "warning" "$JOURNAL_EFFECTIF" 2>/dev/null || echo 0)"
|
|
|
|
echo ""
|
|
echo " doxygen $VERSION_REELLE (référence $VERSION_ATTENDUE)"
|
|
echo " graphviz $(dot -V 2>&1 | sed 's/^dot - graphviz version //; s/ .*//')"
|
|
echo " configuration $DOXYFILE"
|
|
echo " sortie $SORTIE (html/ + xml/)"
|
|
echo " avertissements $AVERTISSEMENTS"
|
|
echo ""
|
|
echo " Rappel : ce compte n'est comparable qu'à un compte produit par CE script."
|
|
echo " Rappel : le graphe d'héritage est tronqué par construction — la classe de"
|
|
echo " base amont SmartChargingManager est hors INPUT. Voir l'en-tête du"
|
|
echo " Doxyfile ; ne pas « réparer » en élargissant le périmètre."
|
|
|
|
if [ "$RC_REGLES" -ne 0 ]; then
|
|
echo ""
|
|
echo " ⚠ L'INDEX DES RÈGLES est incomplet — voir la sortie d'erreur ci-dessus."
|
|
echo " La documentation est produite quand même ; le code de retour, lui, le dit."
|
|
[ "$code" -eq 0 ] && code="$RC_REGLES"
|
|
fi
|
|
|
|
exit $code
|