home.md

@@ -9,8 +9,9 @@ L'objectif de ce wiki est de regrouper les infos glanées en rédigeant des **re
 
 Les fichiers du **wiki** sont au format **markdown** spécifique à gitlab.
 On peut les modifier en ligne: gitlab fournit un éditeur simple et un éditeur plus avancé depuis 2021. Quand vous sauvegardez les modifications vous pouvez personnaliser un "commit message" : en effet, ce wiki est techniquement un dépôt (repository). Il est donc possible de **cloner ce dépôt**, de modifier les fichiers markdown en local puis de mettre à jour le wiki avec un git push.
+Une partie en fin de page rappelle les caractéristiques de ces dépôts. En particulier, il est utile de garder en tête que le readme.md est un fichier du dépôt git principal : quand on le modifie en ligne, on modifie le dépôt, ce qui va créer un conflit quand vous voulez "committer" puis "pusher" les fichiers de scripts que vous avez modifiés sur votre PC : le fichier readme.md qui est présent sur votre copie locale n'est plus identique au fichier distant.
 
-Une autre façon de mettre en ligne de la doc est d'utiliser le module **sphinx**, qui permet également d'extraire la description des classes si on a utilisé un format standard pour les décrire dans le code (docstring + description des paramètres)
+Une autre façon de mettre en ligne de la doc technique est d'utiliser le module **sphinx**, qui permet également d'extraire la description des classes si on a utilisé un format standard pour les décrire dans le code (docstring + description des paramètres)
 
 
 **Sommaire (Table of Content)**
@@ -42,7 +43,7 @@ On donnera ici :
 - quelques inconvénients par rapport à une doc classique : 
     - si on veut profiter du format wiki il faut réfléchir à la structure et consacrer du temps de rédaction (un peu lourd), et bien sûr **apprivoiser le markdown spécifique à GitLab** !
     - le wiki n'est pas consultable hors ligne ; il vaut donc mieux compiler aussi une version pdf, mais a priori il n'est pas facile de passer de plusieurs fichiers md  à un doc unique pdf
-- une note sur les  **autorisations** : le propriétaire d'une page peut gérer des droits d'édition du wiki, indépendamment des droits du repo
+- une note sur la  **nature du readme et du wiki** : Le **readme.md** de la partie dépôt ("repository") est a priori un fichier du dépôt comme les autres, qui est cloné en même temps. En revanche, le wiki est un dépôt indépendant, avec sa propre liste de contributeurs et leurs statut, et sa propre accessibilité (public, restreint...) :  le dépôt principal peut très bien être public et le wiki restreint, ou le contraire.
 
 
 ## Liste des fonctions sélectionnées
@@ -444,17 +445,29 @@ classDef gold fill:#fa0;
 
 Voir [page dédiée sur ce wiki](diagrammes_mermaid).
 
-## tirer parti de la nature de  "dépôt git" du wiki
-Le wiki est lui-même un **dépôt git" (repository), comme le sont les codes dans la partie "Repository". Il est donc possible de le **cloner**, en récupérant les infos via une icône en haut à droite. 
-Gitlab vous propose une liste d'instructions qui n'est valable que sous Linux, mais on peut également cloner et travailler en local sous windows.
-Le principe est le même dans les 2 OS:
+## Connaître la nature du fichier "readme.md" et des pages "wiki" par rapport aux "dépôts git"du projet.
+
+Le readme et le wiki sont des lieux où décrire le projet, en une page pour le readme, en plusieurs pages pour le wiki. 
+Il est facile de les éditer en ligne, des outils d'édition sont disponibles, mais on voit rapidement qu'au lieu de vous proposer de "sauvegarder" vos modifications, on vous propose de "committer", comme pour vos fichiers de scripts.
+Vous pouvez d'ailleurs éviter de "committer" trop souvent en utilisant l'onglet de prévisualisation (`preview`) afin de vérifier que le résultat correspond à ce que vous attendiez.
+
+#### Le fichier `readme.md` de la partie dépôt fait partie de celui-ci.
+
+Le **readme.md** de la partie dépôt ("repository") est un fichier comme les autres, qui est cloné en même temps. En conséquence, si vous le modifiez en ligne, ce qui est tentant, vous modifiez le dépôt. Si vous travaillez sur le dépôt local de votre PC avec des fichiers d'avant le modification du readme, et que vous essayez de "pusher" des commits sur les fichiers de script, il y aura un conflit entre le readme du dépôt distant et celui de votre pc.
+
+##### Le wiki est un dépôt git indépendant
+La partie "repository" et la partie "wiki" sont deux dépôts avec **chacun leurs paramètres** : liste des contributeurs et statut, accessibilité (public, restreint...).
+Le wiki est donc un **dépôt git** (repository) à part entière. Une icône en gaut à droit vous propose de le **cloner**. La liste d'instructions qui s'affiche n'est valable que sous Linux, mais on peut également cloner sous windows. En fait le principe est le même:
 - cloner avec **git clone**
 - vérifier que l'on a récupéré les fichiers et les répertoires (dont `Images`, qui contient les images insérées)
-- effectuer en local des modifications, si possible avec un "bon" éditeur, qui permette la visualisation du résultat et la répercussion de la modification de noms de pages ou de sous-section ("refactoring"). Sous Windows : PyCharm et  VScode permettent d'éditer le mardown. 
-- comme pour un script, une fois les modifications faites il faut puis **"commiter"** et **"pusher"** les modifications sur le dépôt, le wiki se mettra à jour.
+- effectuer en local des modifications, si possible avec un "bon" éditeur, qui propose une coloration syntaxique et la visualisation du résultat (avec le bémol des différences entre markown standard et markdown gitlab), ainsi que des outils bien pratiques comme la répercussion de la modification de noms de pages ou de sous-section ("refactoring"). Sous Windows : PyCharm et  VScode permettent d'éditer le markdown. 
 
+Comme pour n'importe quel script, une fois les modifications faites il faut **"committer"** les modifications puis **"pusher"** sur le dépôt distant, le wiki se mettra à jour.
+
+Cloner le dépôt du wiki est le seul moyen d'accéder au répertoire des illustrations utilisées dans ses pages. 
+
+:warning: pas de « : » dans les noms de fichiers md, sinon le fichier ne peut pas être cloné
 
-A noter que, de la même manière que gitlab permet de régler les droits sur le dépôt du projet, il permet de régler également les droits de lecture et de modification du wiki, indépendamment de ceux du projet.
 
  
 > C:\WorkSpace\2022-AtelierPython\wiki_atelier_python>git clone https://gitlab.irstea.fr/christine.poulard/Atelier_Inkscape.wiki.git
@@ -463,8 +476,6 @@ A noter que, de la même manière que gitlab permet de régler les droits sur le
 
 > C:\WorkSpace\2022-AtelierPython\wiki_atelier_python\Atelier_Inkscape.wiki>git pull origin main
 
-:warning: pas de « : » dans les noms de fichiers md, sinon le fichier ne peut pas être cloné
-
 ## Conversion Markdown => PDF ??
 Solutions non testées...
 La difficulté sera de construire un PDF cohérent à partir de différents fichiers *.md (conserver l'ordre, la structure, les liens...)