1. Les fondamentaux#

Le Fablab, avec ses machines mises à notre disposition, est un lieu d’échange et de partage de savoir faire et d’idées entre personnes de tout horizon. La multidiciplinarité est mise au premier plan car elle permet un travail plus efficace à tous les niveaux. Chacun à quelque chose à apporter et permet d’enrichir les projets.

Voici les outils fondamentaux à maîtriser pour y arriver.

1.1 Avant de commencer#

Avant de s’y mettre, il se peut que, comme moi, vous soyez un peu perdu… Pas de panique ! Je vous conseille de commencer par consulter le travail d’autres étudiants et de comparer les différentes approches. La page de Pauline Mackelbert m’a beaucoup aidée à avancer. Les documentations présentes sur FabZero , ainsi que sur ma page j’espère, vous seront également d’une grande aide.

1.2 La documentation#

Cette première séance au Fablab a pour objectif de nous habituer à documenter notre travail. Cela peut paraître contraignant au début mais il s’agit réellement d’une étape cruciale. La documentation nous permettra ultérieurement de retrouver la procédure suivie pour arriver à un certain résultat sans prendre le risque d’oublier une étape.

1.2.1 Les outils utilisés#

• CLI / Terminal
• Gitlab
• Git
• Markdown
• Visual Studio Code
• Mkdocs

1.2.2 Qu’est-ce qu’un CLI / terminal ?#

Pour ma part, je travaille sur Windows. Mon ordinateur à déjà un terminal intégré, Windows PowerShell, que j’ouvre par la commande touche Windows + X puis j’ouvre terminal. PowerShell est un Interface de ligne de commande (CLI) et moteur d’automatisation conçu par Microsoft qui possède sa propre ligne de commande avec un langage de programmation unique. Quelques commandes de base sont reprises ci-dessous.

Commande	description
ls	List files and folders
cd	Change directory
mkdir	Create a directory
rmdir	Move files or rename files

1.2.3 Git et clé SSH#

Pour éviter de devoir se reconnecter sur Gitlab à chaque modification, nous allons utiliser Git. En utilisant Git, je vais cloner le projet sur mon ordinateur. L’avantage réside dans le fait que nous pouvons apporter toutes les modifications nécessaires à notre copie locale avant de les transférer vers le serveur distant.

Si vous n’avez pas encore Git, il suffit de l’installer puis on vérifie de quelle version il s’agit en entrant la commande git –version dans notre terminal.

La prochaine étape consiste à configurer son username et son adresse mail tels que ceux utilisés sur Gitlab.

Cela étant fait, nous allons créer une clé SSH, une connection sécurisée entre notre ordinateur et le serveur de GitLab. Pour tout comprendre sur la clé SSH, j’ai consulté cette page-ci.

Pour génerer la clé, j’entre la commande ssh-keygen -t ed25519 -C “votre username”. Je remarque qu’il génère ainsi une paire de clés, une étant publique et l’autre privée. J’enregistre ces clés dans un dossier, j’ai la possibilité de choisir un mot de passe.

Voilà, mes clés sont créées !

Maintenant, nous allons ajouter la clé SSH publique à notre compte Gitlab et ne pas partager la clé privée. Cela se fait directement sur notre page Gitlab. Il suffit d’appuyer sur le bouton “ajouter une clé” et d’y coller notre clé publique. On peut vérifier dans notre interface de commande que tout est en ordre.

Ensuite, il nous reste à cloner le projet dans le repository du cours.

Voilà, nous sommes à présent capable de travailler directement sur une copie de notre projet ! Plus qu’à maîtriser les quelques commandes clés listées ci-dessous :

Commande	Rôle
git pull	Télécharger la dernière version du projet
git add -A	Ajouter tous les changements que nous avons fait
git commit -m "message"	Accompagner nos changements d’un message d’explication
git push	Envoyer nos changements sur le serveur

1.2.4 Editeur de texte#

Maintenant, nous allons nous pencher sur la rédaction de notre page web.

Pour éditer notre texte en format markdown, plusieurs options sont possibles. Personnellement, j’ai opté pour un éditeur open-source qui possède une option de pré-visionnage Markdown : Visual Studio Code (Autre possibilité : Atom,…)

En appuyant sur ce lien, vous trouverez toutes les commandes raccourci pour VS Code sur Windows.

Ici aussi, quelques commandes sont à connaître afin de pouvoir modifier le texte, la mise-en-page, etc.

Commande	Affichage
# Titre
## Sous titre
###Sous sous titre
mot en **gras**	mot en gras
mot en *italique*	mot en italique
1. premier élément \n 2. deuxième élément
- premier élément \n - deuxième élément
Image : 
Lien : [nom ](adresse du lien )	nom du lien

1.2.5 Mkdocs#

Mkdocs est un générateur de sites statiques rapide et simple pour créer de la documentation de projet qui nous permettra de prévisualiser le rendu de notre page après chaque modification apportée. Les fichiers de la documentation sont rédigés en Markdown et configurés à l’aide d’un seul fichier de configuration YAML.

1.2.5.1 Installation Mkdocs#

Pour l’installer, rien de plus simple. Il suffit d’ouvrir la fenêtre de commandes. Lorsqu’elle s’ouvre, nous écrivons pip install mkdocs pour lancer l’installation.

Maintenant, nous revenons à notre éditeur de texte, VS Code. Dans la barre d’information en haut à gauche, nous appuyons sur ... puis sur Terminal et enfin sur l’onglet New Terminal.

Dans ce nouveau terminal, nous écrivons mkdocs serve. Un lien apparaît, nous l’ouvrons.

Cette page nous permet de visualiser notre site avant que le pipeline se fasse et de réellement être uploadé sur notre page.

1.2.6 Customiser notre site#

Le rendu visuel de notre page peut être modifié selon nos envies par l’ajout d’images, d’un thème,… Voyons comment faire !

1.2.6.1 Ajouter des images :#

Notre projet comporte les fichiers suivants :

• docs
• • FabZero-Modules
• • module01.md
• • module02.md
• • module03.md
• • module04.md
• • module05.md
• • images
• index.md
• README.md
• images
• requirements.txt
• .gitignore.txt
• mkdocs.yml
• .gitlab-ci.yml

Pour ajouter des photos à notre documentation, il suffit de les ajouter préalablement au dossier images de notre projet. Sur notre éditeur de texte, on les retrouve dans Explorer ( Ctrl + Shift + E ). On effectue ensuite un copié collé et voilà, image ajoutée !

Cependant, la taille de ces images est importante pour :

1. La qualité
2. Le stockage

Généralement, la taille de mes grandes images se situe aux alentours de 600 x 337 px et une qualité de 80%. En augmentant la taille et la qualité, on augmente également le poids du stockage, à éviter donc !

Il faut aussi penser à choisir le format JPG plutôt que PNG pour les images.

Erreur: J’ai d’abord inseré mes photos en faisant un copié collé du lien de l’image. Cette solution me parraissait facile mais elle n’a été que temporaire. En effet, après un certain temps, le lien expire et l’image n’est plus visible. Je vous conseille donc, dès le départ, d’insérer vos images correctement et ainsi d’éviter de devoir toutes les remplacer par après…(Oops !)

1.2.6.1 Modifier le Thème#

Toujours sur VS Code, nous ouvrons l’onglet mkdocs.yml.

Nous pouvons ici modifier toutes sortes d’informations telles que : le nom de notre site, sa description,… et bien sûr, le thème !

Pour modifier notre thème, la partie qui nous intéresse est la suivante :

theme: name: mkdocs # try also cerulean, cosmo, cyborg, amelia, darkly, spacelab, united

Personnellement, j’ai opté pour le thème mkdocs pour le joli rendu bleu mais d’autres thèmes sont disponibles et téléchargeables.

1.3 Gestion de projet#

L’aboutissement de ce cours sera la présentation d’un projet final. Celui-ci, comme tous les projets, peut faire peur au premier abord. Pour nous aider, plusieurs outils peuvent être mis en place. Voici les techniques, inspirées par les propositions de Denis, que j’ai tenté de mettre en place.

Premièrement, il me semble primordial de découper le projet en plusieurs petites tâches. Cela permettra de changer noter point de vue en voyant ça comme de petites étapes attaignables. Sur le long terme, cela permet de rester motivé et diminue donc les risques de prendre du retard.

Ensuite, j’ai établi une hiérarchisation de mes objectifs selon leur ordre d’importance. Cela me permet donc de garantir que les tâches les plus importantes seront réalisées dans les temps. Les détails moins significatifs seront pris en compte à la fin, s’il reste du temps ;-) .

Justement, en ce qui concerne la gestion du temps, la troisième technique que j’ai décidé d’aborder, je me rends compte avec le recul à quel point celle-ci est primordiale. Le retard s’accumule très vite dans un projet alors pour prévenir cela, je conseillerais d’évaluer le temps à consacrer à chaque tâche et de s’y fier ! Si une tâche tire trop en longueur, mieux vaut passer à la suite quitte à y revenir plus tard. Pour cette raison, il peut être intéressant d’inclure à son planning, dès le départ, des moments pour rattraper les petits retards. Ceux-ci sont en effet inévitables à mes yeux alors, organisons-nous !

Voilà, selon moi, les trois méthodes qui permettent la bonne gestion d’un projet.

1.4 Conclusion#

Et voilà, notre page web est maintent créée et nous maîtrisons les outils pour une documentation sans faille ! Notre joli site est fin prêt pour la documetation des séances suivantes !

1.5 Checklist#

Voici la checklist du module1 :

• made a website and describe how you did it
• introduced yourself
• documented steps for uploading files to the archive
• documented steps for compressing images and keeping storage space low
• documented how you are going to use project management principles
• pushed to the class archive