Aller au contenu

Correction des liens de tags dans la documentation française

Billet #178 : Correction des liens de tags cliquables dans la documentation française
Type : Documentation / Correction / Fiabilisation
Composants concernés : mkdocs.yml, docs/tags.md, docs/fr/tags.md, tests/test_docs_config.py, docs/tests/index.md, docs/fr/tests/index.md

1. Contexte

Un écart de comportement avait été observé entre les versions anglaise et française de la documentation : sur les rapports d’activité en français, les tags visibles en haut de page n’étaient pas cliquables, alors qu’ils l’étaient correctement en anglais.

Ce défaut nuisait à la navigation et à l’expérience de consultation, car le filtrage par tags faisait partie du mécanisme prévu pour parcourir rapidement l’historique des interventions du projet.

2. Objectif

L’objectif de cette intervention était de rétablir un comportement cohérent entre les deux langues de la documentation, tout en sécurisant durablement ce correctif.

Concrètement, il fallait :

  • corriger le rendu des liens de tags côté français ;
  • stabiliser la configuration MkDocs / Material / i18n ;
  • ajouter un test de régression pour éviter le retour du problème ;
  • recalculer et réaligner l’indicateur de couverture affiché dans la documentation des tests.

3. Correctif livré

3.1 — Correction du mécanisme de rendu des tags

Le placeholder historique [TAGS] a été remplacé par le marqueur supporté par Material for MkDocs :

  • ###### fr/activity_report/apr-26_bilingual-tag-links-fix.md:1466-1488/name { #fr/activity_report/apr-26_bilingual-tag-links-fix.md:1466-1488/slug }

Ce changement a été appliqué sur :

  • docs/tags.md
  • docs/fr/tags.md

3.2 — Ajustement de la configuration documentaire

La configuration dans mkdocs.yml a été simplifiée afin de s’appuyer sur le comportement nativement supporté par le plugin tags, ce qui a permis de restaurer des liens cliquables aussi bien en anglais qu’en français dans le site généré.

3.3 — Ajout d’un garde-fou automatisé

Le fichier tests/test_docs_config.py a été enrichi avec un test de régression qui vérifie que :

  • le build mkdocs se termine correctement ;
  • les tags EN et FR sont rendus sous forme de liens href ;
  • les pages d’index de tags sont bien générées ;
  • le placeholder brut n’apparaît plus dans le site construit.

3.4 — Mise à jour de la couverture affichée

Le taux de couverture global affiché dans :

  • docs/tests/index.md
  • docs/fr/tests/index.md

a été mis à jour pour refléter la mesure recalculée après l’ajout du nouveau test.

4. Résultat opérationnel

Le comportement est désormais cohérent entre les deux versions linguistiques de la documentation : les tags sont cliquables en français comme en anglais, le filtrage est de nouveau utilisable, et le correctif est protégé par un test automatisé dédié.

Les vérifications exécutées pendant cette intervention ont confirmé :

  • 55 passed, 3 warnings sur la suite pytest ;
  • un build mkdocs build --clean réussi ;
  • une couverture globale recalculée à 95 %.