1. Documentation et gestion de projet#

Cette semaine, j’ai utilisé pour la première fois le terminal de mon ordinateur et je me suis familiarisé avec l’interface en ligne de commande souvent dit CLI (abréviation en anglais). J’ai aussi créé des clés SSH, installé git et visual studio code que j’ai connecté à gitlab. Si tu n’as pas encore commencé ce premier module tout ça peut te paraître incompréhensible, en effet ça fait beaucoup à découvrir en peu de temps mais c’est pourquoi on documente notre travail !

Approche de la documentation#

Etant donné que je suis assez peu intéressé par l’informatique de base, j’étais assez perdu pour ce premier module qui est très axé informatique.
Mais, avec un peu de persévérance et d’entraide j’ai réussi à faire ce qui a été demandé ! Il faut noter que je suis sur mac. Je vais te dire maintenant les étapes que j’ai suivies avec pour chacune de celles-ci les diffcultés rencontrées, Bonne lecture !

Installer Git sur mac#

  • Download Anaconda, qui est un installateur et nous permettra de mettre git sur notre mac

  • Ouvrir le terminal situé dans “autre” dans le launchpad
    terminal

  • Y écrire la commande conda install -c anaconda git

  • Pour checker si git a bien été installé : écrire la commande git dans le terminal, il devrait s’afficher cela : git

Le CLI#

Si tu n’es pas encore familier avec le terminal, il y a quelques commandes à connaitre pour commencer à pouvoir l’utiliser et te balader dans ton ordinateur.

  • ls = affiche le contenu d’un dossier

  • cd nom_du_répertoire_de_destination = permet de naviguer vers un répertoire

  • cd .. = pour retourner dans le dossier parent

  • pwd = affiche le dossier dans lequel tu te trouves

  • open = permet d’ouvrir un fichier, une application, un dossier…

Visual Studio Code et Markdown#

Visual Studio Code est un éditeur de texte que j’utilise à l’instant pour modifier ma documentation. Afin de maîtriser la structure et l’affichage de ce qu’on écrit sur VSC envoyé sur GitLab, j’ai choisi d’utiliser la syntaxe Markdown.
Ce lien vous envoit vers un tutorial que je te conseille vivement de regarder car il m’a donné toutes les informations pour commencer ma rédaction dans VSC.

Je rajouterais à cette vidéo qu’il est utile d’ouvrir une fenêtre preview quand vous modifiez un document dans VSC car vous y verrez comment apparaitra ce que vous êtes en train d’écrire sur le site ! Pour faire ça, appuye sur cmd + k et ensuite sur v en lâchant cmd.

Clé SSH#

C’est sur le mécanisme des clés SSH que Git gère toute sa gestion d’authentification. On parle de clés asymétriques, tu t’apprêtes à créer une clé publique et une privée qui ne devra pas être diffusée. Comment faire ?

  • Ouvrir le terminal

  • Écrire la commande ssh-keygen

  • Un message s’affichera indiquant qu’elles seront créées dans un dossier .ssh sous le nom de id_rsa(.pub) : Taper Enter

  • Overwrite (y/n)? : Écrire y

  • Enter 2 fois

  • Si la fingerprint de votre clé s’affiche, celle-ci est créée !

SSH

  • ls -lAF ~/.ssh pour vérifier ce qu’on a comme clé

C’est à ce moment que j’ai rencontré le soucis qui m’a pris du temps pour ce module : je ne voyais pas le dossier .ssh dans mes documents. Les assistants ont supposé que c’était un dossier caché mais même via le terminal impossible de le retrouver. Si tu rencontres ce soucis : 1. Ouvre Visual Studio Code 2. Donne-lui accès à tes documents 3. Maintenant, dans Users (‘prénomnom’) tu aperçois le dossier .ssh dans lequel se situent id_rsa et id_rsa.pub.

  • Ouvrir id_rsa.pub et copier son contenu
  • Coller dans l’espace SSH keys de GitLab

Si tu veux en savoir plus sur les clés SSH, je t’invite à consulter ce lien !

Modifier notre espace GitLab à partir de Visual Studio Code#

Maintenant que notre clé est créée, on va pouvoir travailler sur VSC pour modifier nos documents (index et modules) sur GitLab. Ces modifications seront ensuite visibles sur le site du fablab (màj les mardi et jeudi).

  • Dans le terminal:

    • git clone "URL", l’URL se situant dans GitLab :
      cloneSSH
    • git config --global user.name "Prénom.Nom"
    • git config --global user.email "ton@email.com"

  • Dans le même espace que l’image ci-dessus, cliquer successivement sur :

    • Visual Studio Code (SSH)
    • Ouvrir le lien
    • Open
    • Le dossier que tu as créé pour le cours
    • Select as repository destination

  • Dans VSC :

    • Ouvrir index.md
    • Y écrire TEST
    • Enregistrer (com + S)
    • Cliquer sur Commit (en haut à gauche)
    • Nommer le changement dans la page COMMIT
    • Com + S et quitter la page COMMIT
    • Cliquer sur Synchroniser les changement

Il faut noter qu’il est possible de faire cela via des commandes git dans le terminal mais j’ai trouvé plus simple cette manière de faire !

Problèmes pour commit#

Après avoir quitté et rouvert Visual Studio Code, je ne voyais plus l’onglet commit quand je rouvrais mes documents. Si vous rencontrez ce problème, voici comment je l’ai résolu :
Dans le terminal, taper git status :

comprob

Comme tu le vois, j’avais des changements qui n’étaient pas disposés à être commit ; j’ai utilisé la commande git restore pour résoudre ce problème et ai ainsi pu continuer ma documentation tranquillement !

Les images#

Seuls les formats jpeg et png sont acceptés par VSC. Je vous conseille de mettre les images dans le dossier ‘images’ déjà existant dans votre dossier docs lui-même dans Users. Ensuite, il suffit d’écrire ![image](nom_de_l'image.jpg) dans VSC.

Modifier la taille et la résolution d’une image est très simple sur mac, il suffit d’ouvrir votre image et cliquer sur :

im

MkDocs#

C’est un générateur de site (en local) qui va t’être utile pour vérifier l’affichage de ta documentation. Cela te permettra aussi de changer le nom de ta page fabzéro !
Tu pourras aussi mettre un thème original 😎

  • Installe MkDocs

  • Ouvre ton terminal

  • Tape mkdocs serve pour intier le serveur, tu obtiens son lien ici :

mkdocs

  • Tape pip install mkdocs-bootswatch pour installer la collection des thèmes

  • Ouvre mkdocs.yml se situant dans ton espace prénom.nom créé lors de l’ouverture du dépôt git que tu as effectué auparavant

  • Change le nom du thème selon tes goûts !

Gestion de projet et importance de la documentation#

Nous avons été introduit à quelques méthodes pour une bonne gestion de projet - personnel ou de groupe.

Parmi celles-ci, j’ai trouvé particulièrement intéressant la technique de développement en Spirale, que j’ai essayé d’appliquer tout au long de mon travail pour ces 5 modules en préparation à la phase “travail de groupe” du cours.
Celle-ci stipule, en gros, qu’il vaut mieux s’attaquer à une tâche au bon moment même si c’est pour avancer peu dans celle-ci mais d’une façon efficace et pertinente, plutôt que de travailler les tâches en série et ainsi ne pas être certain d’avoir un projet final abouti.

spiral

La figure illustre bien cette approche en spirale. On avance dans le travail petit à petit en explorant chaque tâche une à une pour voir notre projet avancer de façon plus globale.

Typiquement, de semaines en semaines j’ai alimenté ma documentation après chaque module pour ensuite revenir dessus la retravailler quand j’avais plus de temps, d’inspiration ou d’outils.