1. Markdown#

Ce tutoriel concerne markdown, et donc votre documentation. Vous y retrouverez ici tout (ou presque) ce dont vous aurez besoin afin d’écrire votre documentation. Ceci part de la base telle que la modification de votre documentation en passant par toutes les intégrations, les compression, etc. En clair, vous retrouverez ici toute l’aide nécessaire afin d’écrire une bonne documentation.

1.1 Documentation#

Modification locale#

Si vous avez effectué une copie locale de votre repository comme expliqué au module 1, vous devriez maintenant être en mesure de modififer le contenu de votre documentation. Pour ce faire il vous faudra passer par un éditeur de texte, je conseille fortement Visual Studio Code puisqu’il est très intuitif et facile à prendre en main et qu’il possède quelques fonctionnalités intéressantes. Une fois le logiciel installé, pressez les touches ctrl+K et ensuite pressez ctrl+O. Vous devriez pouvoir sélectionner votre dossier à ouvrir comme ceci: Une fois votre dossier importé tous vos fichiers seront à disposition et vous pourrez commencez à les éditer, voici ce que àa donne à l’heure où j’écris ces lignes:

Preview#

Vous remarquerez que la manière dont vous apparaissent ces lignes sont différentes, ceci est dû à la syntaxe markdown. Afin d’écrire correctement et de m’assurer que tout ce que j’ajoute à ma documentation se fait correctement il faut pour cela que je puisse avoir une idée de ce à quoi va ressembler le résultat final, il nous faut une preview. Pour ce faire, 2 choix s’offrent à vous.

VSC Preview#

Le premier est la preview intégrée dans Visual Studio Code, que vous pouvez ouvrir grâce aux touches ctrl+K puis V. Ceci vous ouvrira une fenêtre juste à coté de votre éditeur vous donnant un aperçu comme suit:
Cependant toutes les commandes ne sont pas comprises telles que le {:style=”display:block; margin-left:auto; margin-right:auto”}, ceci vous donne donc une vague idée mais rien de précis. En plus de cela le thème n’est pas ajouté donc votre résultat final sera toujours différent de ce quer vous voyez.

Mkdocs Preview#

Afin de remédier à ça nous allons localement générer un site en utilisant mkdocs qui sera également utilisé pour générer le site réel, ceci vous donnera donc une preview exacte et qui se modifie en temps réel. Afin de l’utiliser vous devez déjà avoir installé mkdocs (cf. module01), vous rendre dans le terminal au niveau de votre copie locale et enfin taper la commande: 

mkdocs serve

Vous devriez avoir ceci comme message:

Cliquez alors sur le lien (ou copier-collez le lien dans votre navigateur) afin d’arriver sur votre site local qui sera exactement comme votre site réel. Vous pouvez reconnaitre le site local grâce à l’adresse qui sera 127.0.01:8000:

Envoi des modifications#

Une fois que vous avez fini de travailler vous devez envoyer vos modifications sur le repository gitlab, ceci se fait à l’aide de GIT. Rendez-vous simplement dans le terminal à l’emplacement de votre copie locale et tapez les commandes suivantes:

git add -A

git commit -m "COMMENTAIRE"

git push

Ceci vous permet d’envoyer les modifications avec le commentaire précisé lors du commit:

Veillez à push vos modification régulièrement, dès que vous avez fini votre session de travail ou même plusieurs fois par session de travail, envoyez vos modifications afin que votre repository soit toujours à jour par rapport à votre copie locale. Ceci est obligatoire si vous travaillez sur plusieurs machines, sur une seule machine c’est important et une bonne habitude à prendre mais ça ne vous pénalisera pas.

1.2 Liens#

Ici rien de bien compliqué, vous pouvez soit ajouter un lien en l’écrivant directement, soit rendre du texte cliquable pour rediriger vers le lien souhaité comme ce test. Afin de faire ceci vous utiliserez la syntaxe [Texte](Lien). Pour le lien donné en exemple, la syntaxe utilisée est [test](https://www.google.com/).

Ceci fonctionne avec tous les liens, évitez cependant de rediriger vers des liens inconnus ou des sites non fiables car on ne sait jamais ce qui se cache derrière alors que votre documentation est censée être fiable.

1.3 Images#

Ajout d’images#

Cette partie sera probablement la plus utilisée, puisque les images sont très courantes dans une documentation. Afin d’en ajouter, la syntaxe est:

![](Chemin/NomImage)

Dans mon cas pour reprendre une des images que j’ai utilisé ma syntaxe a été:

![](images/tuto1/Capture.png){:style="display:block; margin-left:auto; margin-right:auto"}

Vous remarquerez que j’ai utilisé une option ({:style=”display:block; margin-left:auto; margin-right:auto”}) qui me permet de mettre les images à la bonne taille et à la bonne place afin d’avoir une documentation plus épurée. Il existe une multitude d’option possibles, celle-ci étant la plus courante je la reprends ici mais si vous souhaitez quelque chose de spécifique il vous faudra recherchez ce qui vous convient.

Modification d’images#

Lors de la création d’un site, nous cherchons toujours à réduire au maximum l’espace que celui-ci prend. Les images remplissent très rapidement cet espace, nous cherchons donc souvent à réduire leur taille au maximum. Pour de faire, nous avons plusieurs options.

Logiciel#

La première option consiste à simplement installer un logiciel afin de traiter les images. Un bon logiciel connu et Opensource est GIMP, mais n’importe quel logiciel peut être utilisé. Le tutoriel ne concerne pas tellement l’utilisation de GIMP, je vous laisse donc toutes les instruction ici. Vous y retrouverez toutes les informations principales qui vous permettront de redimensionner et/ou compresser vos images afin de réduire leur taille.

Package CLI#

La seconde consiste à passer directement par le terminal en installant un package qui vous permet de redimensionner et/ou compresser vos images de manière très rapide, cependant vous n’avez pas d’aperçu puisqu’il n’y a pas d’interface graphique. Je vous conseiller d’utiliser GraphicsMagick, qui une fois installé vous donnera la liste des commandes à l’aide de la commande gm -help. La commande la plus susceptible d’être utilisée sera convert -resize qui vous permet de réduire la taille de vos images comme ici:

gm convert -resize 160x90 Capture.png SmallCapture.png

Cette commande permet de sélectionner l’image Capture.png, réduire sa taille à 160px par 90px, et avoir cette image dans un nouveau fichier appelé SmallCapture.png.

1.4 Vidéos#

YouTube#

Afin d’intégrer une vidéo YouTube à votre documentations, plusieurs possibilités existent. Vous pouvez ajouter la miniature de la vidéo choisir à votre page en la rendant cliquable et redirigeant vers la vidéo même ou autre, mais dans la plupart des cas c’est l’ajout d’une vidéo avec un lecteur intégré qui intéresse (comme je l’ai fait aux modules 1 et 2).
Pour ce faire, il vous suffit d’ajouter la ligne suivante à l’endroit où vous voulez intégrer votre vidéo en veillant à bien mettre l’ID de votre vidéo cible:

<iframe width="560" height="315" src="https://www.youtube.com/embed/YoutubeID" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

ex: 
<iframe width="560" height="315" src="https://www.youtube.com/embed/7LxrYSD8UY8" title="Installation Ubuntu" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Vidéo personnelle#

Enregistrement#

Si vous souhaitez ajouter une vidéo personnelle dans votre documentation, vous pourriez cherchez à enregistrer votre écran. Pour ce faire je vous conseille OBS Studio qui est très intuitif et vous permet d’enregistrer votre écran très facilement. Ceci n’est valable que pour un enregistrement d’écran, si vous avez pris une vidéo avec votre portable il vous suffit simplement de la transférer sur votre machine afin de l’ajouter.

Intégration#

Afin d’intégrer une vidéo que vous avez localement sur votre machine, il vous suffit de mettre ces lignes à l’endroit où la vidéo doit apparaitre et mettant un bon chemin d’accès vers votre vidéo:

<video>
<source src="PATH/VIDEO.mp4" type="video/mp4">
</video>


ex:
<video>
<source src="fabzero-modules/module1/test1.mp4" type="video/mp4">
</video>

Attention cependant à compresser vos vidéos afin de ne pas surcharger votre repository inutilement, pour ce faire vous pouvez utiliser différents outils tels que des logiciels de montage vidéo (Adobe Premiere Pro, Wondershare, DaVinci Resolve, etc.), des sites internet même si cette solution n’est pas optimale (Veed.io, Clideo, etc.) ou la solution la plus simple en CLI est d’utiliser ffmpeg. Avec ffmpeg la commande utilisée sera:

ffmpeg -i input.mp4 -b 800k output.mp4

où input.mp4 est le nom de votre vidéo de base, 800k est le débit de 800.000 bits/s (au plus celui-ci est bas au plus la vidéo sera compressée) et output.mp4 est le nom de sortie de la vidéo compressée.

1.5 Syntaxe étendue#

Dans le module1, j’ai donné un tableau comprennant la syntaxe basique de markdown. Dans cette section nous verrons là syntaxe étendue qui est plus rare, mais qui reste cependant très utile si vous souhaitez faire une documentation claire et très visuelle.

Tables#

Les tables peuvent être utilisées dans différents cas, personnelement je les utilise plutôt comme une sorte de listes où mettre toutes les informations sur une même lignes n’est pas suffisament clair. Pour la syntaxe nous utilisons simplement des barres verticales (|) en tant que séparateur de colonnes et un minimum de 3 tirets (-) en tant que séparateur de titre de colonnes, toutes les autres lignes peuvent être ensuite mises les unes à la suite des autres. Pour exemple ma syntaxe pour l’aide-mémoire du module 1 était:

Le résultat qui en est sorti est:

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
![Texte](image.jpg) 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

Vous pouvez créer un tableau avec autant de lignes et de colonnes que vous souhaitez, cependant je ne vous conseille pas de dépasser les 3 colonnes voire 4 si leurs contenu est relativement court. Vous remarquerez également que j’ai utilisé des backslash (\) devant certains symboles dans le tableau, ceci est dû à la propriété du backslash en markdown qui indique que le caractère suivant doit être pris comme un caractère textuel et non comme un caractère engendrant une commande. Ceci permet donc d’écrire la syntaxe de l’écriture italique par exemple, mais sans mettre le texte en italique dans le tableau.

Ecriture de code#

Vous pourriez également ajouter des blocs de codes comme j’en ai utilisé durant toute ma documentation. Il en existe deux type: les lignes intégrées au texte, et les blocs séparés du texte.

Ligne de code#

Pour ceci, nous utiliserons le caractère ` au début et à la fin de chaque mot (ceci étant indiqué dans le tableau de la syntaxe markdown) afin de le mélanger au texte. La syntaxe utilisée sera par exemple:

Ceci est un `CodeDeTest` afin de voir le résultat MarkDown.

Et le résultat sera:
Ceci est un CodeDeTest afin de voir le résultat MarkDown.

Blocs de code#

Intégration#

Ces blocs de code sont généralement plus utilisés car ils permettent soit d’intégrer du gros code, soit de mettre en évidence une ligne puisque celle-ci prend toute la largeur de la page. Pour sa syntaxe elle est presque identique à celle de la ligne: on commence et on finit un bloc de code par 3 ` ce qui donne une syntaxe du genre:

Ceci nous donne le résultat:

    // Voici un exemple de syntaxe de code
    // 

    //Auteur: Christopher BILBA

    ...

Langage#

Une petite particularité de ces blocs de code sont la couleurs des mots clés. Lors du premier ``` vous pouvez préciser à coté le langage dans lequel vous avez écrit afin d’avoir des couleurs correspondantes aux mots-clés utilisés. Voici par exemple avec un code en python: 

    #Voici un code inutile en python

    def UselessFunction(bool):
        a = 4
        b = 0
        for i in range(a):
            b += 1
        text = "Wdym it is an useless function?"
        return None

Notes de bas de page#

Vous pourriez également vouloir intégrer des notes en bas de page, pour ce faire rien de plus simple. Intégrer directement votre note avec l’explication juste en dessous mais ne vous inquiétez pas, elle se retrouvera bel et bien à la fin de la page de cette manière:

Ceci est un test[^1], afin de créer une note en bas de page[^2]

[^1]: Test extrêmement intéressant (ou pas).

[^2]: Et oui ça veut bien dire en bas de la page

Attention, ces notes peuvent être réparties un peu partout mais veillez bien à ne pas mettre le même index pour des notes différentes.

Listes#

L’ajout de listes est également possible, vous les avez peut-être déjà vues si vous avez lu ma documentation avant d’arriver ici. Il en existe 2 types principaux que nous verrons ici ainsi qu’un type avec une syntaxe particulière que je mentionne également.

Listes non-ordonnées#

La première sorte des listes sont les listes non ordonnées. Comme son nom l’indique elle permet de lister un nombre infini d’éléments sans ordre précis. Sa syntaxe est relativement simple: on commence une ligne par un tiret (-) et on met l’élément de sa liste derrière, on passe à la ligne et on répète l’opération. Voici ce que cela donnerait en syntaxe:

- Voici une liste
- Rajout d'un élément
- Encore un élément
- Dernière ligne

Ce qui donne le résultat suivant:

Il est également possible d’imbriquer des sous-liste dans cette liste en effectuant une indentation. La syntaxe devient alors:

- Voici une liste
    - Voici une sous-liste
        - Voici une sous-sous-liste
    -Un autre élément
- Rajout d'un élément
- Encore un élément
- Dernière ligne

Les sous-listes s’affichent ainsi:

Il est cependant très important de faire attention à 2 choses lorsque vous ajoutez des listes dans votre documentation. La première est le respect de l’espace en le tiret (-) et la suite du texte: “- Test” sera bien considéré comme un élément de la liste mais “-Test” sera simplement considéré comme du texte. La seconde est la ligne d’espace que vous devez mettre avant et après la liste, c’est à dire que vous passez une ligne supplémentaire afin de laisser de l’espace pour que la syntaxe soit bel et bien comprise. Si vous avez tout respecté et que vous travaillez sur Visual Studio Code, la tirets de la liste s’afficheront en bleu pour vous indiquer que la syntaxe est bonne comme suit:

Listes ordonnées#

Le principé des listes ordonnées reste le même, mais au lieu d’avoir des tirets au début de chaque ligne vous pouvez mettre des chiffres afin de mettre en avant un certain ordre. Ceci revient donc à faire:

1. Premier élément
2. Deuxième élément
3. Troisième élément
4. ...
5. n-ème élément

Le résultat sorti sera:

  1. Premier élément
  2. Deuxième élément
  3. Troisième élément
  4. …
  5. n-ème élément

Liste de tâches#

Un sous-type de listes fréquemment utilisée est la liste de tâche. Il s’agit tout simplement d’une liste non-ordonnée à laquelle on rajoute la syntaxe [X] ou [] entre le tiret et l’élément afin d’indiquer si la tâche a été faite ou non. Vous pourriez avoir quelque chose du genre:

- [X] Expliquer le Markdown
- [X] Documentation sur la compression d'images
- [X] Expliquez les listes
- [] Montrez comment configurer un site
- [] Ajouter toutes les images au module

Ceci vous donnera le résultat suivant:

1.6 Configuration du site#

Mkdocs.yml#

Afin de changer la configuration de votre site, vous devrez modifier le fichier mkdocs.yml qui vous a été fourni au départ. Si vous l’ouvrez vous y retrouverez un certains nombre de lignes qui sont assez explicites mais regardons ce que chacune d’entre elle fait:

Voici les informations principales que vous devez changer afin de configurer votre site, pour le reste soit nous n’y toucherons pas soit j’y reviendrai juste après car certaines explications nécéssitent une section complète.

1.7 Thèmes#

Thèmes pré-installés#

Vous pouvez également changer le thème de votre site, c’est à dire son allure générale. La bilbiothèque de thèmes bootswatch est déjà installée sur votre repository, mais afin de l’utiliser avec mkdocs serve vous devrez l’installez localement à l’aide de la commande:

pip install mkdocs-bootswatch

Les thèmes compris dedans sont:

Amusez-vous à tester tous les thèmes si vous le souhaitez, cependant je vous conseille de prendre votre temps afin de choisir un thème convenable. Certaines particularités de certains thèmes peuvent vous paraître amusantes ou sympathiques, mais le thème pourrait rendre le site difficile à lire ou ne pas convenir à vos besoins dans le cadre de la documentation. Veillez donc à garder en tête que le site sert de documentation et qu’à l’avenir il sera consulté par des tiers.

Une fois votre thème choisi, rendez-vous dans le fichier mkdocs.yml mentionné précédemment et mettez le nom du thème choisi en valeur de theme name. Votre thème est désormais changé.

Thèmes personnalisés#

Les changement de thèmes que nous venons de voir conviendrons généralement, mais pas forcément à tout le monde. Pour ma part rien n’était assez satisfaisant dans la bibliothèque bootswatch, j’ai donc modifié certaines choses par moi-même afin que le repository GitLab installe les thèmes ajoutés.

Pour commencer il vous faudra déjà trouver un thème qui vous plaît en recherchant sur internet, ou bien créer votre propre thème. La seconde option peut attirer la curiosité de certains mais rassurez-vous, vous n’avez probablement pas les compétences et surtout pas le temps de développer un thème pour un simple site de documentation. Néanmoins si un courageux passe par ici, libre à lui d’essayer mais attention au temps!

Une fois le thème trouvé, vous devez retrouver sa commande d’installation qui sera généralement:

pip install mkdocs-NomDuTheme

Supposons que votre thème s’appelle “theme_test”, la commande devrait être:

pip install mkdocs-theme_test

Installez le sur votre machine et ensuite testez le localement à l’aide de mkdocs serve. Si l’aperçu vous convient alors nous pouvons passer à l’installation du thème sur le site réel. Pour ce faire nous aurons besoin de modifier 2 choses: le mkdocs.yml et le requirements.txt. Pour comprendre le but de ces modification, regardons de plus près le gitlab-ci.yml:

image: python:3.8-slim

before_script:
  - pip install -r requirements.txt

pages:
  script:
  - mkdocs build
  - mv _site public
  artifacts:
    paths:
    - public
  only:
    refs:
      - schedules
    changes:
      - "**/*.md"

En informatique les instructions s’exécutent ligne par ligne, ce fichier fait donc les actions suivantes:

La partie nous intéressant ici est l’installation des dépendances, car nous ajouterons un thème qui n’est pas connu pour le moment. Dans le fichier requirements.txt nous allons donc rajouter le “theme_test” choisi précédemment, pour ce faire il suffit de rajouter le ligne mkdocs theme_test (où theme_test est le nom de votre thème). Votre fichier devrait maintenant être:

mkdocs
mkdocs-bootswatch
mkdocs-windmill-dark

Une fois ceci fait, rendez-vous dans le mkdocs.yml afin de modifier le nom de votre thème au bon endroit:

theme:
    name: theme_test

Votre sera maintenant installé avant chaque exécution du script ce qui vous permettra de l’utiliser pour votre site. A noter que vous pouvez ajouter tous les packages python que vous souhaitez utiliser de la même manière, seule leur utilisation changera mais l’ajout se fera toujours dans le requirements.txt.

1.8 Ajout de fichiers#

Vous pourriez également être interéssés par l’ajout de fichiers ou carrément de sections hors modules telles que cette section dans laquelle vous lisez mes tutoriels, vous verrons ici comment faire.

Section complète#

Afin d’ajouter une section complète, vous devez créer un nouveau dossier mais qui doit obligatoirement se retrouver à l’intérieur du dossier docs puisque dans le mkdocs.yml nous avons spécifié que le contenu du site est entièrement dans le dossier docs. En ajoutant un sous-dossier vous créez une section hors modules tel que montré ci dessous:
En cliquant sur “New Folder…” après avoir fait un clic droit sur le dossier docs, vous introduisez le nom de la section que vous souhaitez faire apparaître. A noter que si vous créer un sous-dossier ne contenant pas de fichiers .md (uniquement des images par exemple) aucun nouvelle section ne sera créée.

Fichiers individuels#

Maintenant que vous avez une nouvelle section de prête, il faut y ajouter les fichiers .md pour le contenu. Pour ceci rien de plus simple, dans votre nouveau dossier faites un clic droit et “New File…” puis introduisez un nom du genre Fichier01.md. Attention, pour une raison de practicité je vous conseille d’avoir tous les noms de fichier identiques à l’exception du nombre les suivant. Lors que la création du site, chaque fichier et donc sous-section est prise par ordre alphabétique des fichiers, en les appelant tous fichiers01.md, fichier02.md, …, fichierXX.md vous vous assurez que les fichiers seront toujours dans l’ordre que vous avez prévu. Ce serait dommage si votre dernier module se retrouve tout au début parce que vous avez fait commencé son nom avec un “A” par exemple.

1.9 Builds du site#

Cette section servira plut$ot à mentionner des possibilités qu’autre chose, faire un tutoriel complet sur cette partie est une plus grosse charge de travail que la totalité de la documentation écrite dans le cadre de ce cours. Pour faire simple, si vous savez ce que vous faites et que cherchez à modifier votre site comme vous le souhaitez alors amusez-vous. Cependant sans un très bonne connaissance de CSS, HTML et JavaScript je vous conseille de ne même pas chercher à faire ce que j’expliquerai dans cette section étant donné que vous risquer de causer des erreurs et de perdre énormément de temps pour n’avoir au final aucun résultat.

Modification des fichiers#

Il vous faudra d’abord générer les fichiers build, ici rien de bien compliqué mkdocs peut le faire pour vous à l’aide de la commande 

mkdocs build

Une fois ceci fait un nouveau dossier nommé _site sera crée dans votre copie locale.

Votre dossier _site apparaît désormais tout en haut de votre liste dans votre éditeur de texte.

Vous pouvez maintenant y naviguer et commencer à lire les dizaine de milliers de ligne de code qui sont écrites. Evidemment, vous ne le ferez pas et moi non plus d’ailleurs. Comme dit précédemment je ne vous invite pas à toucher à ces fichiers mais puisque la curiosité est un vilain défaut il fallait que je m’amuse un petit peu avec. La partie qui nous intéresse le plus sera ici la partie CSS, et plus précisément les fichier base.css, bootstrap-3.3.7.css et highlight.css. Ces fichiers-ci comportent à eux 3 quasiment toute la mise en page du site, et leurs modifications permet de changer tout ce que nous voulons telles que les couleurs, les polices, la taille de chaque texte, la taille et le style de la navbar, les éléments pris en compte dans la table des matières, etc.

Libre à vous d’essayer certaines choses mais si vous ne vous y connaissez pas je vous conseille plutôt de travailler sur un copie de vos fichiers de manière locale à l’aide de `mkdocs serve.

Envoi des modifications#

Si vous cherchez à envoyer vos modification effectué c’est que vous avez un minimum de connaissances dans le domaine et que vous rencontrez probablement une erreur que vous n’arrivez pas à résoudre donc voici certaines choses à regarder:

Limitations#

Il y aurait encore beaucoup de choses à expliquer mais ceci dépasse de très loin le cadre du cours, j’y ai simplement fait mention avec de brèves explications afin de documenter ce que j’ai fait personnelement mais je me limiterai à ça ici. Si vous souhaitez en apprendre plus un apprentissage long et fastidieux néanmoins intéressant.

1.10 Conclusion#

Ceci conclut mon tutoriel pour cette partie, il s’agit probablement de la partie la plus longue et la plus complexe notamment les points 1.7 si vous créez votre thème et le point 1.9 si vous avez choisi de refaire votre site. Pour la plupart des questions vous pouvez trouver des réponses avec une petite recherche internet mais si nécessaire n’hésitez pas à me contacter pour toute question concernant les modules ou tutoriels liés:

  1. Discord: bball_8
  2. Mail: christopher.bilba@ulb.be (à éviter en général si vous voulez une réponse rapidement)