Analyse des dépendances documentaires

Site d’origine

Vous gérez un projet dans lequel vous devez produire 35 documents et le client vous en fournit tout autant, mais dans trois versions différentes ? Comment faites-vous pour assurer la cohérence de tout ça ? Comment faites-vous pour vous assurer que vous avez bien répercuté la modification d’un document sur l’ensemble des documents qui le référence ?

Ce n’est pas simple et c’est pour ça que j’ai développé un outil qui m’a bien aidé et qui pourra peut-être vous rendre service.

DocDep : un analyseur de dépendances documentaires

L’outil est disponible dans ce projet gitlab. Il requiert pas mal de dépendances (de quoi analyser les documents PDF et word, ce qui n’est pas toujours simple) aussi il vous sera sans doute plus simple d’utiliser l’image docker.

Voici quelques cas d’usage :

Analyse de cohérence

cd ~/s/c939a  # local project directory
fd -0 -d 2 "C939.*(doc|pdf)" Doc_Projet |
   xargs -0 docker run --rm -v "$PWD":/w -w /w -t \
      gitlab.aix.systerel.fr:5000/outils/docdep:latest docdep.py \
      --ignore '^(C939_MDL_DOC|.*XX).*'

La commande ci-dessus trouve (avec fd) l’ensemble des documents projet et appelle l’outil en lui demandant d’ignorer le modèle de document et les documents dont le nom contient XX. Cela donne par exemple :

WARNING  L10T_O115_D405-1 appears under different versions : [02.01, 02.00]
WARNING    ([02.00] referenced in C939_PQL [B], C939_ACA [B], C939_STA [B], C939_RVA [B], C939_RVO [C], C939_MDL [B], C939_RVMDL [B], C939_PRTMDL [B], C939_MU [B], C939_FVL [C], C939_PRT [C], C939_PGD [B], C939_PVD [B], C939_SRC [B], C939_RVTO [C], [02.01] referenced in C939_FMTS [C])
WARNING  L10T_O115_D405-4 appears under different versions : [02.01, 02.00]
WARNING    ([02.01] referenced in C939_MDL [B], C939_RVMDL [B], C939_PRTMDL [B], C939_SRC [B], [02.00] referenced in C939_MU [B])

On met facilement le doigt sur les incohérences du référentiel documentaire.

Analyse d’impact

L’outil permet aussi de déterminer quels sont les documents concernés par la modification d’un ou plusieurs autres documents.

Par exemple, la commande :

fd -0 -d 2 "C939.*(doc|pdf)" ~/s/c939a/Doc_Projet |
   xargs -0 docker run --rm -v "$PWD":/w -w /w -t \
      gitlab.aix.systerel.fr:5000/outils/docdep:latest docdep.py \
      --ignore '^(C939_MDL_DOC|.*XX).*'  -c L10T_O115_D405-2 -c L10T_O115_D405-4

retourne la liste des documents qui peuvent être transitivement concernés par la modification de l’un des deux documents client : L10T_O115_D405-2 ou L10T_O115_D405-4, à savoir :

C939_RVMDL, C939_MDL, C939_RVTO, C939_FMTS, C939_PRTMDL, C939_PRT, C939_SRC, C939_MU

Affichage du graphe de dépendance

Le graphe de dépendance peut être affiché sur la sortie standard avec l’option -p, ce qui donne par exemple :

C939_ACA [B] → C415_MOG [J]
C939_ACA [B] → C939_FMTS []
C939_ACA [B] → C939_MDL []
C939_ACA [B] → EN 50128:2011/A2:2020 []
C939_ACA [B] → L10T_O115_D405-1 [02.00]
C939_ACA [B] → L10T_O115_D405-4 []
C939_ACA [B] → SQ_MDL_DOC [G]
C939_FMTS [C] → L10T_O115_D405-1 [02.01]
C939_FMTS [C] → L10T_O115_D405-2 [02.01]
…

Il peut aussi être affiché sous forme graphique avec l’option -d qui produit un fichier html.

Attention

Cet outil a été développé pour être utilisé sur des projets Systerel avec des documents d’entrée fournis par ALSTOM. Il utilise des heuristiques pour reconnaître les documents référencés (voir la section idoine du README).

Il est possible qu’il ne fonctionne pas tout à fait correctement pour votre projet. Je vous invite à :

  • vérifier une fois manuellement que toutes les références sont bien vues,
  • signaler par un ticket tout problème rencontré,
  • proposer d’éventuels correctifs sous forme de merge requests.

Commentaires