1. Gestion de projet et documentation#
Dans ce module nous verrons tout ce qui concerne la gestion de projet et la documentation. Ceci servira à créer un bon environnement de travail qui facilitera la documentation et permettra donc un gain de temps.
1.1 Environnement de travail#
Dans un premier temps nous verrons ici tout ce qui est relatif à l’installation et à la configuration de l’espace de travail. Ceci inclus donc l’installation d’une machine virtuelle sous Linux, l’installation de git, la copie locale du repository et une liste d’outils utiles pour ce fonctionnement.
Linux Supremacy#
Pour travailler correctement il vous faudra bien évidemment un pc, cependant différents problèmes peuvent survenir selon les différents systèmes d’exploitations (Os) pouvant être installés (MacOS, Windows, Linux étant les plus courants). Linux étant selon moi le meilleur choix possible en terme d’efficacité, c’est ce que je conseille à tout le monde. Peu importe votre système d’exploitation, Linux pourra toujours être utilisé sur votre machine grâce à une machine virtuelle (VM)
Installation d’Ubuntu#
Afin d’installer votre VM vous aurez besoin de 2 choses: le logiciel VirtualBox ainsi qu’un fichier .iso pour Ubuntu. Les étapes sont relativement simples tant qu’on s’y connait un minimum, il suffit de télcharger le logiciel et le fichier, lancer VirtualBox et configurer sa machine virtuelle avec les performances souhaitées ainsi que le fichier .iso pour la faire tourner sous Ubuntu.
Cependant pour les personnes n’étant pas à l’aise ou ayant des doutes, une petite recherche sur YouTube vous permettra d’avoir les étapes illustrées ainsi que et des explications. Voici une vidéo qui je l’espère sera encore valide à l’heure ou vous lisez ceci:
Copie locale du repository#
Une fois tout ceci fait vous devriez maintenant vous retrouver sur votre machine virtuelle avec linux. Si vous ne l’avez jamais fait, vous devez vous apprendre à vous servir du terminal que vous pouvez retrouver dans vos applications (glissez le dans vos applications favorites sur le coté, ou ouvrez-en un à chaque fois avec Ctrl+Alt+T).
Installation de GIT#
Afin d’installer et de configurer GIT vous devrez taper quelques simples commandes dans le terminal.
Tout d’abord il vous faut installer GIT grâce à la commande:
sudo apt-get install git
Une fois ceci fait, tapez les deux commandes suivantes indépendamment en remplaçant ce qui se trouve entre les guillements par votre nom d’utilisateur personnel et adresse e-mail:
git config --global user.name "your_username"
git config --global user.email "your_email_address@example.com"
Voilà pour GIT, c’est rapide et simple à installer. Maintenant nous devons faire en sorte de “lier” votre machine à votre repository se trouvant sur GitLab
Clé SSH#
Pour cela vous devez générer une paire de clé SSH, une qui sera privée et restera sur votre machine ainsi qu’une autre publique que vous ajouterez à votre profil sur GitLab. Ceci est également fait avec des commandes très rapidement.
Pour générer une paire de clés SSH il vous faudra choisir son type, choisissez une des commandes ci-dessous et utilisez la dans le terminal afin de générer vos clés (entre guillemet mettez un commentaire pour votre clé, personnellement j’ai mis “Laptop” pour mon pc portable et “Home” pour mon pc fixe):
ssh-keygen -t ed25519 -C "<comment>"
ssh-keygen -t rsa -b 2048 -C "<comment>"
Appuyez sur votre touche Enter 3 fois afin de confirmer le chemin d’accès et de ne pas mettre de mot de passe. Maintenant que les clés sont générées nous devons récupérer la clé publique, pour ce faire rendez vous dans votre dossier .ssh grâce à la commande cd .shh.
Tapez ensuite la commande:
cat ~/.ssh/id_ed25519.pub
Ceci affiche votre clé SSH publique, copiez la en faisant un clic droit puis copy afin de la copier dans votre clipboard. Rendez-vous sur ce lien, cliquez sur “ajouter une clé” et ajoutez votre clé que vous venez de copier. Cette étape étant terminée, vous pouvez désormais cloner votre repository sur votre machine.
Clone#
Une fois toutes ces étapes terminées, ouvrez un terminal dans le dossier où vous souhaitez stocker la copie locale de votre repository. Vous pouvez voir la liste des éléments se trouvant dans les dossiers actuels avec la commande ls, et vous pouvez vous déplacer dans un dossier avec la commande cd nomDuDossier. Ces deux commandes remplacent l’interface graphique (GUI) que nous avons l’habitude d’avoir, elles correspondent au fait d’avoir les éléments affichés et de double click dessus afin d’y accéder.
Rendez-vous sur la page de votre repository, et sous l’onglet “cloner” copier ce qui se trouve dans la partie “cloner avec SSH”. Une fois ceci fait, tapez la commande
git clone elementCopieDepuisGitlab
#La commande pour mon repository était:
git clone git@gitlab.com:fablab-ulb/enseignements/2023-2024/fabzero-experiments/students/christopher.bilba.git
Effectuez maintenant la commande git pull afin de récupérer le dossier localement, modifiez le avec un éditeur de texte (Visual Studio Code, VSCodium, etc.), ajoutez vos changements avec les commandes git add -A et puis git commit -m "commentaires", et enfin envoyez vos changement sur le repository se trouvant sur le gitlab avec la commande git push.
Outils utiles#
Cette section a été écrite dans le but de faciliter le travail des personnes souhaitant se lancer dans la documentation de leur projet. Vous y retrouverez ici la liste des commandes, outils, extensions, etc. que j’ai pu utiliser afin d’effectuer ma propre documentation et qui ne sont pas toujours très claires, voire inconnues.
Cependant comme vous vous en doutez, ceci vous aidera mais ne vous expliquera pas comment faire. Vous pouvez retrouvez mon tutoriel vous permettant de rédiger une bonne documentation ici
Commandes GIT#
| Commande | Description |
|---|---|
| git –version | Afficher la version de git utilisée |
| git status | Vérifie si la copie locale est à jour, en retard ou en avance |
| git pull | Met à jour la copie locale en fonction du repository |
| git add -A | Ajoute la totalité des fichiers en préparation du commit |
| git add yourFileName | Ajoute le fichier précisé en préparation du commit |
| git commit -m “Commentaire” | Effectue un commit avec le commentaire écrit entre guillemets |
| git push | Permet de push les changements fait localement sur le repository de gitlab |
| git restore yourFileName | Remet le fichier précisé à son précédent état |
| git config –global user.name | Change le nom d’utilisateur pour git de manière globale |
| git config –global user.email | Change l’email pour git de manière globale |
| git config –global –list | Affiche la liste d’éléments de configuration de git |
Commandes terminal#
| Commande | Description |
|---|---|
| ls | Affiche tous les éléments présents dans le dossier courant |
| cd yourFileName | Permet de changer le dossier courant en se déplacant dans celui précisé |
| cd file_1/file_2/file_3/…/file_X | Permet de se déplacer suivant un chemin entier déjà donné |
| mkdir yourFileName | Permet de créer un dossier du nom donné |
| rmdir | Retire les dossiers vides |
Mkdocs#
| Commande | Description |
|---|---|
| sudo apt install mkdocs | Installation de mkdocs via sudo |
| sudo apt install python3-pip | Installation de pip nécéssaire à mkdocs et ses thèmes |
| pip install mkdocs | Installation de mkdocs via pip |
| pip install mkdocs-bootswatch | Installation de la librairie de thèmes bootswatch pour mkdocs |
| mkdocs serve | Crée un site local se modifiant en temps réel |
1.2 Documentation#
Une fois l’espace de travail organisé, il est temps de commencer à travailler sur la documentation. Je vais reprendre ici tous les conseils et astuces qui m’ont permis d’écrire ma propre documenation afin que cela puisse servir de modèle/aide.
Format#
Il est important de garder à l’esprit le format de cette documentation. En effet il s’agit ici d’un site internet, certes créé dans le cadre du cours mais il reste public. Le fait qu’il s’agisse d’un site permet une totale liberté quant aux choix effectués, il est cependant important de garder une certaine cohérence afin de ne pas perdre les éventuels lecteurs.
Le fait de ne pas avoir de contraintes de taille limite comme la plupart des étudiants ont pu avoir lors de documentations/rapports effectués au cours de leurs études, il s’agit ici de ne pas se retenir. Si des explications sont données sur un certain sujet nécessitant un schéma, une illustration vidéo, le renvoi vers une page détaillée, etc. ce format permet de le faire sans le moindre soucis. Attention cependant à ne pas en abuser, ceci reste une documentation dans le cadre du cours et l’objectif ici n’est pas de retaper les pages wikipédia de toutes les éléments techniques abordés ou d’en faire un portfolio d’artiste avec 18 schémas par pixel².
Une bonne solution serait de se limiter aux informations nécessaires à la compréhension dans la documentation des modules, et soit de renvoyer vers des liens externes (sites, vidéos, forums, etc.) soit de mettre une catégorie annexe sur votre site reprenant toutes ces informations supplémentaires que vous souhaitez donner.
Illustrer les explications données à l’écrit reste une bonne pratique peu importe les choix effectués. Cependant des divergences ont lieu en fonction du public cible et de votre objectif concernant ce site.
Public cible et objectif?#
Pour ma part j’ai fait le choix de cibler plus particulièrement les étudiants choisissant ce cours les années suivantes, tout en gardant à l’esprit qu’il pourrait y avoir des visiteurs externes. Ce choix implique le fait de ne pas devoir présenter le cours dans son entiereté puique celui-ci sera connu des étudiants, mais j’en fais quand même une mention à l’occasion afin que d’éventuels visiteurs comprennent le cadre dans lequel les travaux présentés ont été effectués.
Ceci a été mon choix puisqu’il correspond à mon objectif, cependant ce n’est peut-être pas le même que le vôtre et que vous ciblerez donc un autre public (tel que votre professeur, même si ce n’est pas le meilleur choix selon moi).
En parlant d’objectif, si vous avez lu ma documentation jusqu’ici vous avez sûrement compris que je cherche à guider le plus possible les étudiants des années suivantes, principalement avec ce module-ci. En effet j’ai essayé d’écrire une sorte de tutoriel au point 1.1 à suivre pas à pas afin que chacun puisse se créer un espace de travail comfortable, et ensuite au point 1.2 j’essaye de donner une méthode de travail afin que chacun puisse démarrer le plus rapidement et avec un objectif clair en tête.
Maintenant à vous de déterminer l’utilité que vous donnerez à votre site et en conséquence vous ferez les choix correspondants à cet objectif .
Régularité#
Maintenant intervient le sujet qui fâche: le travail régulier. Il n’y a pas de secret, si vous souhaitez écrire une bonne documentation et effectuer des bons projets il faut travailler régulièrement.
Avec du travail en dernière minute, vos projets ne fonctionneront tout simplement jamais (si ça fonctionne passez à la lotterie en rentrant) parce que vous n’aurez pas le temps de faire des tests. Afin de réussir il faut d’abord échouer, comprendre les raisons de cet échec afin d’y appliquer des corrections et réessayer à nouveau jusqu’à obtenir le résultat attendu. Vous vous en doutez, cette méthode d’essai-erreur ne peut pas être appliquée si vous n’avez pas le temps de faire des essais.
Concernant la documentation elle se fait en grande partie après avoir avancé sur les projets, à moins d’être devin auquel cas vous réussirez à documenter ce qui n’existe pas encore. Mais pour le commun des mortels, vous devez avoir un travail à documenter sinon vous n’avez tout simplement pas de documentation. Et même si par un miracle vous réussissez à vous en sortir avec le projet en dernière minute, vous n’aurez pas le temps d’écrire toute la documentation de celui-ci si vous ne le faites pas au fur et a mesure. De plus en écrivant tout à la fin de votre projet vous risquer d’oublier certains points ce qui est dommage.
En clair, travailler régulièrement vous permettra de venir à bout de vos projets et de leurs documentations.
Markdown#
J’ai créé une section “Tutoriels” que vous pouvez retrouver en dessous des modules du FabZero dans laquelle vous retrouverez un tutoriel complet sur la mise en forme de la documentation. Cependant il est relativement long, je vous mets donc ci-dessous un petit aide-mémoire reprenant les éléments les plus utilisés si le tutoriel est trop long pour vous:
| Syntaxe | Description |
|---|---|
| # Titre | Crée un titre |
| ## Sous-titre | Crée un sous-titre |
| … | … |
| ###### Sous(x6)-titre | Crée un sous(x6)-titre |
| *Italique* | Met le texte en italique |
| **Gras** | Met le texte en gras |
| `code` | Met le texte sous le format code |
| ```Bloc Code``` | Permet d’écrire un bloc de code sur plusieurs lignes |
| [Texte](https://votreLien.com) | Rajoute un lien sur un texte le rendant cliquable |
|  | Intègre une image au lieu où le texte est écrit |
| 2 espaces fin de ligne | Effectue un passage à la ligne après celle comportant les espaces |
| — | Place une ligne horizontale sur toute la page |
Voici également une liste de liens vous permettant d’avoir une liste plus complète si vous cherchez quelque chose ne se trouvant pas dans ce tableau: