Modifier le fichier

Guide de contribution à la documentation

La documentation K-Sup est réalisée en utilisant le langage Markdown (cf syntaxe Markdown Bitbucket). Il est possible de la modifier directement à partir d'un navigateur. En revanche pour l'ajout d'un nouveau fichier, il faudra passer par un poste de développement.

Mise à jour de la documentation via l'interface web

1. En haut de chaque page, un lien permet d'accéder au fichier source de la page pour mettre à jour la documentation.
2. Copier l'ensemble du fichier
3. Aller sur l'éditeur web approprié (https://onlinemarkdowneditor.dev/)
4. Coller le contenu dans la toolbox de l'éditeur
5. Si vous avez besoin d'ajouter des images il faut dans l'éditeur web :
   1. Ajouter l'image dans la toolbox
   2. Cliquer sur l'image pour faire apparaître les boutons contextuels
   3. Cliquer sur le bouton de droite pour ajouter un texte alternatif et le valider
6. Après avoir modifié le contenu, il faut copier le contenu modifier à partir du mode source de la toolbox
7. Il faut ensuite retourner à l'emplacement des sources sur Gitlab et accéder aux sources en cliquant sur le bouton Modifier

4. Remplacer le contenu du fichier dans la page web avec celui copié 5. Pour valider la modification il faut

1. Cliquer sur le bouton commit en bas de la page

2. Renseigner un message sur le fenêtre de validation. Attention, le message doit toujours commencer par docs : xxxx. 1. Si vous n'avez pas ajouté d'image, vous pouvez valider en cliquant sur le bouton commit 2. Si vous avez ajouté des images, il faut alors créer une pull request pour les joindre afin que des développeurs puissent les intégrer. Pour ce faire il faut : 1. Sur la fenêtre de validation, cocher la case Créer une pull request pour ce changement 2. Puis cliquer sur le bouton Créer une pull request (laisser le nom de la branche généré) 3. Sur la fenêtre de création d'une pull request, ajouter les différentes images dans le champ description 4. Cliquer sur le bouton créer 5. Demander à un développeur d'intégrer les images au markdown (utiliser des chemins relatifs)

Ajout de nouveaux fichiers à la documentation

La construction du site de documentation est réalisée en se basant sur une convention pour l'emplacement des fichiers mardown. Pour ajouter un ficher, il faut donc respecter cette convention.

1. Les fichiers doivent être placés dans le repository du module K-Sup concerné. Si le fichier concerne une problématique générique au produit K-Sup, il doit être placé dans ce projet (K-Sup Documentation).
2. L'emplacement du fichier dépend de sa portée
   1. Si le fichier a une portée fonctionnelle, il doit être placé en respectant la cartographie K-Sup (cf K-Sup - Référentiel produit)
      1. Dans un répertoire docs/func/contenus pour les composants liés aux contenus
      2. Dans un répertoire docs/func/modules pour les composants liés aux modules
      3. Dans un répertoire docs/func/socle pour les composants liés au socle
   2. Si le fichier a une portée technique, il doit être placé dans un répertoire docs/tech.
3. Dans chaque répertoire, il faut créer un fichier SUMMARY.md contenant l'organisation du répertoire et le lien vers les différents fichiers. Exemple :
   1. Exemple pour de la documentation fonctionnelle

- [Fiche Article](func/module/article-func.md)

2. Exemple pour de la documentation technique

- [Article]()
  - [Article](tech/article/article-tech.md)
  - [Propriétés](tech/article/article-properties.md)

Attention, pour la documentation des différents modules K-Sup, les chemins des fichiers doivent contenir le nom du repository du projet sur git.

Gestion des ressources

Les images et autre ressources doivent être rangées dans un répertoire resources (il est possible d'ajouter des sous-répertoires)

Templates de documentation

• Template pour la description des propriétés