Spaces:
Running
Running
File size: 3,040 Bytes
1766da1 2b782d0 1766da1 2b782d0 1766da1 2b782d0 1766da1 2b782d0 1766da1 081c957 1766da1 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 | # Étendre le glossaire contextuel
Le glossaire affiché dans le panneau latéral du rapport est défini en
YAML, une entrée par terme, dans `picarones/reports/html/glossary/{lang}.yaml`.
## Ajouter un terme
Éditez **les deux fichiers** `fr.yaml` et `en.yaml` (les tests vérifient
la symétrie) :
```yaml
my_new_metric:
title: "Titre court — abréviation"
definition: >-
2-3 phrases de définition formelle. Tout en pur texte, pas de HTML.
measures: >-
Ce que la métrique mesure concrètement.
usage: >-
Cas d'usage factuels (pas prescriptifs : « utilisé en X » et non
« à choisir si vous êtes Y »).
limits: >-
Limites connues, pièges fréquents.
reference: >-
Référence bibliographique canonique (auteur, année, titre).
```
Tous les champs (`title`, `definition`, `measures`, `usage`, `limits`,
`reference`) sont **obligatoires** et non vides. Les tests
(`test_each_entry_has_required_fields`) le vérifient.
## Brancher l'entrée à une colonne du rapport
Dans `picarones/reports/html/templates/view_ranking.html` (ou un autre fichier
de vue), ajoutez l'attribut `data-glossary-key` sur l'en-tête de
colonne :
```html
<th data-col="my_new_metric" class="sortable"
data-glossary-key="my_new_metric"
data-i18n="col_my_new_metric">Ma métrique</th>
```
Au démarrage du rapport, `injectGlossaryButtons()` parcourt tous les
`th[data-glossary-key]` et ajoute un petit bouton `?` cliquable.
## Règles à respecter
1. **Pas de HTML dans le contenu** : le rendu côté JS utilise
`textContent` pour les paragraphes (sécurité XSS). Si vous mettez
du HTML, il sera affiché en clair.
2. **Pas de prescription** : le champ `usage` doit être factuel
(« historiquement utilisé pour X ») et non prescriptif (« à choisir
si vous voulez Y »). Picarones ne recommande jamais.
3. **Référence vérifiable** : citez un auteur/année réels. Les utilisateurs
peuvent suivre la référence pour creuser.
4. **Symétrie FR/EN** : les deux fichiers doivent contenir les mêmes
clés. Le test `test_fr_and_en_have_same_keys` casse en cas
d'asymétrie.
## Ajouter une langue
Créez `picarones/reports/html/glossary/de.yaml` avec la même structure que
`fr.yaml`. Le loader le détecte automatiquement via
`Path.glob("*.yaml")`.
Pour qu'un utilisateur puisse choisir cette langue :
1. Ajouter `picarones/reports/html/i18n/de.json` (traductions de l'interface).
2. Aucune modification de code requise — `load_glossary("de")` marchera.
## Tests
Le fichier `tests/test_glossary_customize.py` couvre
automatiquement :
- Chargement et fallback (langue inconnue → FR).
- Symétrie FR/EN.
- Présence des champs obligatoires.
- Termes critiques garantis (16 entrées dont CER, WER, Friedman, etc.).
- Pas de HTML dans le contenu.
Ajoutez votre nouvelle entrée à la liste `critical` du test
`test_critical_terms_are_documented` si elle est référencée par une
colonne du rapport — cela garantit qu'un futur refactor ne la
supprime pas par accident.
|