1. Gestion de projet et documentation#

Lors de la séance d’éxercices de Project Management, il a été demandé de réaliser les actions suivantes :

  • Créer un site et décrire le processus.
  • Se présenter.
  • Documenter les étapes pour télécharger des fichiers vers les archives.
  • Documenter les étapes pour compresser des images et réduire l’espace de stockage.
  • Expliquer l’utilisation des principes de Project Management.
  • Pousser les modifications vers les archives.

1.1. Par où commencer ?#

Dans ce chapitre, les premières étapes pour aborder ce module sont expliquées. Si quelque chose ne fonctionne pas ou si les explications manquent de détails, untutoriel est disponible pour une description plus approfondie, surtout si l’on travaille sur Windows ou macOS.

1.1.1. Remarque sur le système d’exploitation#

Les commandes présentées dans cette documentation sont exécutées sur un système d’exploitation Ubuntu, qui utilise un terminal basé sur Unix. Si vous utilisez un autre système d’exploitation comme Windows ou macOS, certaines commandes peuvent différer ou ne pas fonctionner directement.

  • Sous Windows, vous pouvez utiliser un environnement Unix via Windows Subsystem for Linux (WSL), qui permet d’exécuter Bash (un terminal Unix) sur Windows.

  • Sous macOS, bien que le terminal soit également basé sur Unix, certaines commandes ou chemins peuvent être légèrement différents.

1.2. Créer un compte et se connecter à GitLab#

Pour accéder aux fichiers et modifier son site personnel, il faut d’abord se créer un compte GitLab. Une fois le compte créé, le professeur donnera accès au dépôt GitLab où se trouvent tous les fichiers nécessaires à la modification du site.

1.3. Clé SSH#

Maintenant que le compte gitlab est créé, il faut associer une clé SSH à ce compte. Depuis la page princpale, on peut cliquer sur sa photo de profile en haut à gauche et sélectionner Edit profile.

Ensuite dans le menu à gauche, cliquer sur SSH Keys.

On se trouve maintenant sur la page où il faudra ajouter la clé SSH.

1.3.1. Création d’une clé SSH#

Pour créer une clé SSH, il faut ouvrir un terminal avec ctrl + alt + t et et exécuter la commande ssh-keygen -t rsa -b 4096 -C "ton_mail@gmail.com", où il faudra modifier le texte entre guillemets avec l’adresse mail utilisée pour le compte gitlab.
Une fois la ligne de commande exécutée, il est demandé où on souhaite stocker la clé sur notre machine. Par default elle sera stockée à cette location /home/user/.ssh/id_rsa. Pour accepter l’emplacement par default il ne faut rien écrire et juste taper sur la touche Enter. Le terminal demandera ensuite un passphrase, ce qui est optionel, donc par facilité on ignore cette étape et un appuie sur Enter deux fois de suite.

Si tout s’est bien déroulé, une image randomart image de la clé devrait apparaître sur le terminal.

1.3.2. Récupérer la clé SSH#

Pour récupérer la clé SSH, on peut ouvrir le fichier qui la contient dans le terminal avec la commande cat ~/.ssh/id_rsa.pub. Ensuite on peut sélectionner l’entièretée du texte et le copier avec ctrl + shift + c.

1.3.3. Ajouter la clé sur gitlab#

Maintenant qu’on possède notre clé SSH dans le presse-papier, on peut la coller dans gitlab dans la case pour ajouter une clé.

Une fois la clé collée, il est possible de lui attribuer un titre, mais le titre par défaut est suffisant. On peut alors cliquer sur Add Key et voilà ! Notre clé SSH est reliée à notre compte gitlab !

1.3.4. Vérification#

Afin de s’assurer que la clé SSH est bien liée avec gitlab, on peut ouvrir un terminal ctrl + alt + t et entrer la commande ssh -T git@gitlab.com. Le terminal demandera de confirmer la connexion, il faudra alors entrer yes et puis taper sur Enter. Si tout s’est bien passé, un message de bienvenue apparaîtra !

1.4. Installer git sur sa machine#

Pour la suite, il faudra installer git sur sa machine. Pour vérifier si git est déjà installé, on peut ouvrir un terminal ctrl + alt + t et taper la commande suivante git --version. Si la commande git n’est pas reconnue par le terminal, il faudra installer git.

1.4.1. Installer git#

Pour installer git c’est très simple, il suffit de taper la commande sudo apt install git dans le terminal. Le mot de passe de l’utilisateur sera demandé car on utilise le terme sudo (il permet d’exécuter une commande en tant que super-utilisateur). Une fois git installé, on peut le configuer avec les commandes git config --global user.name "pseudo" et git config --global user.email "ton_mail@gmail.com" en modifiant pseudo avec ton nom par exemple et ton_mail@gmail.com avec ton adresse mail. Cette configuration permettra à git de faire son boulot comme il faut lorsqu’on voudra commit et push notre travail.

1.5. Cloner son repository gitlab#

On va maintenant récupérer les fichier/dossiers de gitlab pour les cloner sur notre machine.

Sur la page du projet dans gitlab, il faut cliquer sur la petite case bleu où il est écrit code et ensuite copier l’URL de la séction Clone with SSH.

Une fois l’URL copier, on va ouvrir un terminal ctrl + alt + t et se positionner dans le bureau avec la commande cd Desktop/. On va maintenant créer un dossier avec la commande mkdir repo_gitlab et vérifier s’il a bien été créer avec la commande ls. On devrait donc voir le nom repo_gitlab de notre dossier dans le terminal. Une fois le dossier créer, on va aller dedans avec la commande cd repo_gitlab/. Mainteant on va pouvoir cloner le projet de gitlab avec la commande git clone URL_COPIER (remplacer URL_COPIER avec l’URL de la séction Clone with SSH sur gitlab).

Si tout s’est bien passé, un nouveau dossier est apparu dans le dossier repo_gitlab ! Ce dossier comporte les fichiers/dossiers qu’on retrouve sur le site gitlab ! Pour voir un peu ce qu’il y a dedans, il suffit d’entrer la commande cd nom.prénom/ (le nom du dossier cloner devrait ressembler à ton nom.prénom, pour vérifier utilise la commande ls) et ensuite avec la commande ls tu verras ce qui s’y trouve !

1.6. Installer un IDE#

Pour modifier les fichiers du site, il est recommandé d’utiliser un IDE (Integrated Development Environment). Un IDE proposé par le professeur est VSCodium mais j’utilise personnelement VSCode. Il est également possible de modifier les fichiers directement dans le terminal avec Vim par exemple mais je n’expliquerais pas comment l’utiliser ici.

Si tu préfères choisir ton propre IDE, tu es libre d’aller chercher sur internet celui qui te sied comme ici par exemple !

1.7. Modifier les fichiers et les upload sur gitlab#

1.7.1. Ouvrir le dossier dans l’IDE#

Avec notre IDE favoris installé, on va pouvoir ouvrir le dossier où se trouve les fichiers à modifier pour notre site. Dans VSCode, il suffit de cliquer sur File/Fichier en haut à gauche et ensuite sélectionner Open Folder/Ouvrir Dossier. Une fenêtre devrait s’ouvrir et il faudra aller chercher dans ses dossiers le dossier contenant les fichiers du site (il devrait s’appeler nom.prénom). Si tu as suivis les étapes du point 1.5, le chemin vers le dossier est Desktop/repo_gitlab/nom.prénom.

1.7.2. Ouvrir le fichier README.md#

Une fois le dossier ouvert, on trouvera tous les fichiers/dossiers dans le menu à gauche de l’écran. Si on clique sur le fichier README.md, on verra le fichier brute en Markdown qui s’ouvre. On peut alors modifier le texte comme bon nous semble.

1.7.3. Modifier le fichier et le sauvegarder#

Maintenant on va pouvoir modifier le fichier. Dans la première ligne, on peut ajouter à côté du texte # Read Me un petit mot, par exemple TEST. Une fois la modification effectuée, on va appuyer sur les touches ctrl + s pour sauvegarder le fichier.

1.7.4. Commit et Push#

Les modifications faites dans le fichier README.md ne sont visibles que sur notre machine pour l’instant. On aimerait bien que les modifications se retrouvent sur gitlab afin que notre site soit lui aussi modifier. Pour ce faire il va falloir ouvrir un terminal ctrl + alt + t et aller dans le dossier du projet avec la commande cd Desktop/repo_gitlab_nom.prénom, si tu as fait comme dans le point 1.5. Une fois dans le dossier, on va pouvoir exécuter une commande pour voir l’état de notre projet. Avec la commande git status, on pourra voir les fichiers modifiés, supprimés, ajoutés, etc… Ici on voit que notre fichier README.md est modifié.

Maintenant il va falloir utiliser la commande git add .. Celle-ci permet de “preparer” le répertoire courant et tous ses sous-répertoires pour être ensuite validées dans l’historique du dépôt. Après il faut entrer la commande git commit -m "TEST", où le texte entre les guillemets est le message du commit. Et pour finir, la commande git push.

Une fois ces commandes efféctuées, on peut aller vérifier si les modifications ont bien été faites sur gitlab, et c’est bien le cas ! On retrouve le mot TEST qu’on a ajouté dans le fichier README.md.

1.7.4.1. Résumer#

Pour résumer, une fois que le dossier est modifié et qu’on souhaite envoyer sur gitlab, il faut faire les commandes dans l’ordre :

  • git add .
  • git commit -m "message"
  • git push

1.8. Utiliser Markdown#

On est maintenant capable de sauvegarder et archiver notre travail sur gitlab. Il ne reste plus qu’à apprendre comment modifier les fichiers Markdown pour pouvoir écrire sa documentation. Grâce à ce tutoriel, on peut apprendre très vite les bases de Markdown.

1.8.1. Extensions VSCode#

Dans l’IDE VSCode, on peut facilement installer des extensions pour nous faciliter la vie lorsqu’on écrit du code. Avec Markdown, ce serait bien de pouvoir voir à quoi ressemble le rendu de ce qu’on écrit. Grâce à l’extension Markdown Preview Enhanced on peut le voir directement dans notre IDE.

Pour télécharger l’extension, il faut séléctionner l’onglet Extensions dans le menu à gauche, ensuite écrire Markdown dans la barre de recherche et pour finir installer l’extension Markdown Preview Enhanced.

Maintenant on peut avoir un apperçu du rendu du fichier dans lequel on se trouve avec les touches ctrl + k puis v.

1.8.2. Mkdocs#

Une autre manière de voir le rendu est d’utiliser le package Mkdocs.

1.8.2.1 Installer Mkdocs avec pip#

Une façon d’installer Mkdocs est d’utiliser le gestionnaire pour pacquets de python pip.

Il faut d’abord avoir python d’installé sur sa machine. Pour vérifier, dans un terminal, on peut entrer la commande python3 --version. Si python n’est pas installé, on peut entrer la commande sudo apt install python3 python3-pip qui installera python et pip en même temps.

Maintenant on peut installer Mkdocs avec la commande pip install mkdocs. Si comme moi vous avez une erreur de type externally-managed-environment, on peut résoudre le problème en créant un environnement virtuel pour notre projet. Vous pouvez retrouver tout ce qu’il y a à savoir sur les environnement virtuel en python ici.

Si l’installation fonctionne directement ou si vous avez eu le courage de créer un venv, la commande pour avoir un aperçu du fichier est mkdocs serve (il faut être dans le dossier du projet avec le terminal pour que la commande fonctionne). Un lien sera donner dans le terminal et avec un ctrl + clique dessus une page local host s’ouvrira dans votre navigateur internet.

1.8.2.1 Installer Mkdocs avec pip#

Si on ne préfère pas créer un environnement virtuel, on peut utiliser le gestionnaire de paquets système apt avec la commande sudo apt install mkdocs. Une fois l’installation effectuée, on va aller dans le dossier du projet avec le terminal (cd Desktop/repo_gitlab/nom.prénom comme au point 1.5).

Une fois dans le bon dossier, avec la commande ls on va vérifier si on a un fichier mkdocs.yml, si c’est le cas on se trouve au bon endroit !

Maintenant avec la commande mkdocs serve on devrait obtenir un lien pour avoir un aperçu de notre fichier en local host dans notre navigateur. Mais erreur … :

Il suffit juste d’installer les themes avec pip mais il faut donc créer un venv mais on va éviter de le faire. Une autre solution simple est de modifier le thème utiliser. Pour ce faire on va ouvrir le fichier mkdocs.yml dans notre IDE et modifier le nom du thème par mkdocs.

Après avoir sauvegarder le fichier, on va pouvoir utiliser la commande mkdocs serve et obtenir un lien ! Il suffit de ctrl + clique dessus et une page local host s’ouvre dans le navigateur web.

1.9. Images#

Il est intéressant de modifier les images qu’on souhaite ajouter à la documentation. On peut les modifiers de plusieurs manières dont par exemple crop une image, écrire dessus, encadrer des éléments, etc … Il faut aussi faire attention lorsqu’on met des images sur le site qu’elle ne soient pas trop volumineuse.

Pour faire toutes ces modifications, on peut utiliser GIMP. Pour installer l’application, on peut suivre ce tutoriel.

1.9.1. Crop une image#

Pour crop une image dans Gimp, il suffit d’ouvrir une image dans le logiciel et séléctionner dans la barre de menu Outils/Tools, ensuite Transform tools et puis Crop. On peut aussi utiliser les touches shift + c.

Ensuite, il faut encadrer la partie de l’image qu’on souhaite garder et taper sur la touche Enter

1.9.2. Réduire la résolution#

Pour réduire la taille du fichier de l’image, on peut utiliser l’option scale image dans Gimp. Dans la barre de menu, sélectionner Image puis Scale Image…

Une petite fenêtre devrait s’ouvrir dans laquelle il faudra modifier la taille de l’image (le plus long côté doit faire environ 600 px). Il faudra aussi faire attention à ce que la résolution soit au maximum de 75 pixels/in.

1.9.3. Utilisation des principes de “Project Management”#

Une technique de project management qu’on a appris est le développement en spirale. Cette technique consiste à réaliser un projet petit pas par petit pas. On commence d’abord par les bases, puis on ajoute à chaque fois de plus en plus de contenu et de détails. J’ai utilisé ce principe pour la réalisation de la documentation des modules. Pour commencer il y a la prise de note lors du cours théorique, il s’agit de la première petite spirale. Ensuite la remise au propre et la structure des notes et la deuxième petite spirale. Pour la troisième spirale, c’est l’ajout des photos. Ensuite l’ajout des liens, des détails plus technique et tout autres inforamtions importantes forme la dernière spirale. Cette technique sera aussi utilisée lors de la création du projet, avec le mindset d’y aller petit à petit et ne pas vouloir finir immédiatement.

1.9.4. Pour aller plus loin#

Pour en connaitre plus sur Gimp, on peut aller voir la documentation.