Markdown & Diagrams

Markdown - Historique

Définition

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as a markup language that is easier to read in its source code form. Markdown is widely used for blogging and instant messaging, and also used elsewhere in online forums, collaborative software, documentation pages, and readme files.

-- wikipedia

Objectif du markdown

1. Écrire de la documentation

2. Façile à écrire

3. Façile à lire directement

4. Façile à convertir en HTML

Le markdown est utilisé partout!

• github (gitlab) présente les fichiers avec une extension .md comme markdown

• slack

• Intégration avec tous les IDE

• Jira

• jupyter (ces notes de cours)

• hugo (mon blogue)

• https://gist.github.com/

• https://obsidian.md/

GitHub Flavored Markdown

• La version du markdown que nous utilisons usuellement

• Extension de markdown pour ajouter des fonctionnalités non présentes dans la première version

• Retrait de fonctionnalités insécures

Tous vos répo github devraient avoir un README.md

• Écrit en markdown

• Qui explique le projet

Où pratiquer sont markdown

Utilisons gist!

Recette

1. logger-in dans github

2. aller sur https://gist.github.com/

3. Choisir un nom de fichier qui fini par .md

4. cliquer sur "Preview" pour pré visualiser votre résultat

Markdown

Markdown (titres)

# Gros title 

Lorem ipsum dolor sit amet, consectetur adipiscing elit

## Title 

sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation

### Petit title
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

HTML

Gros title

Lorem ipsum dolor sit amet, consectetur adipiscing elit

Title

sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation

Petit title

Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Markdown (liste non ordonnée)

* oignons

* carottes

* tomattes

HTML

• oignons

• carottes

• tomattes

Markdown (liste numéroté)

1. oignons

2. carottes

3. tomattes

HTML

1. oignons

2. carottes

3. tomattes

Markdown (tableaux)

https://www.tablesgenerator.com/markdown_tables

| Tables   |      Are      | Cool |
|:---------|:-------------:|-----:|
| col 1 is |  left-aligned | 1600 |
| col 2 is |    centered   |   12 |
| col 3 is | right-aligned |    1 |

HTML

Tables	Are	Cool
col 1 is	left-aligned	1600
col 2 is	centered	12
col 3 is	right-aligned	1

Markdown (Équations pour walid)

Ceci est une equation inline: $e^{i\pi} + 1 = 0$

Ceci est une equation  $$\sin^2{x} + \cos^2{x} =  1$$

HTML

Ceci est une equation inline: $e^{i\pi} + 1 = 0$

Ceci est une equation $$\sin^2{x} + \cos^2{x} = 1$$

Markdown (code block)

Ceci est un code block

```python
def append(lst, x):
    return lambda ishead : x if ishead else lst
```

```js
function cons(lst,x){
    return function (isHead){
        return isHead ? x : lst; 
    }
}
```

HTML

Ceci est un code block

def append(lst, x):
    return lambda ishead : x if ishead else lst

function cons(lst,x){
    return function (isHead){
        return isHead ? x : lst; 
    }
}

Documentation

• Cheatsheet: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

• github documentation: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github

• Original post: https://daringfireball.net/projects/markdown/syntax

Mermaid

C'est quoi?

• Un language pour faire beaux diagrams
• Qui est rendu vraiment populaire comme extension avec le markdown
• Facile à utiliser dans le html

---
title: Example Git diagram
---
sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

La manière de travailler avec mermaid

1. prendre un exemple pas trop loin de ce que nous voulons https://mermaid.js.org/syntax/flowchart.html

2. modifier l'exemple dans l'éditeur https://mermaid.live/edit

Documentation:

• https://mermaid.js.org/intro/getting-started.html

• https://mermaid.live/edit

Diagrammes UML

L'UML est le langage de modélisation standard le plus utilisé. Il définit 13/14 modèles (vues) différents basés sur une apparence (look-and-feel) similaire.

Diagramme de cas d’utilisation (use case diagram): Permet de modéliser les actions/fonctionnalités faites par un acteur (utilisateur) avec un futur logiciel.

Diagramme de séquence: Diagramme d'interaction qui met l'accent sur la chronologie de l'envoi des messages. Normalement, chaque cas d'utilisation détaillé a un diagramme de séquence. Le diagramme de séquence aide a faire le lien entre le cas d'utilisation (haut niveau) et le diagramme de classe (bas niveau).

https://en.wikipedia.org/wiki/Unified_Modeling_Language

Nous, nous verrons deux type de diagrams

• Use Case Diagrams

• Sequence Diagrams

Use Case Diagram

Tout ce cours est un plagit flagrant d'un vidéo de 12 minutes

• https://www.lucidchart.com/pages/uml-use-case-diagram

• https://www.youtube.com/watch?v=4emxjxonNRI

C'est quoi un "use case"?

Un cas d'utilisation, bloc fonctionnel ou cas d'usage (« use-case » en anglais), définit en génie logiciel et en ingénierie des systèmes une manière d'utiliser un système qui a une valeur ou une utilité pour les acteurs impliqués

Le cas d'utilisation correspond à un ensemble d'actions réalisées par le système en interaction avec les acteurs en vue d'une finalité.

L'ensemble des cas d'utilisation permet ainsi de décrire les exigences fonctionnelles d'un système en adoptant le point de vue et le langage de l'utilisateur final.

-- wikipedia

Cas d’utilisation (use case)

Objectifs des cas d’utilisation:

• Capturer le comportement désiré du système
• Spécifier ce que le système fait (fonctions), mais pas comment il le fait.
• Servir d’entente entre les développeurs, les utilisateurs et les experts sur les fonctions disponibles et sur la façon d’interagir avec le système.
• Servir à valider l’architecture logicielle qui sera développée.

Un cas d’utilisation est un document narratif qui décrit la séquence d’évènements dans laquelle un acteur (un agent externe) utilise un système pour accomplir un processus.

Cas d’utilisation (use case)

Les cas d’utilisation peuvent être spécifiés avec différents niveaux de détail:

• Format de haut niveau

  • Abrégé, peu détaillé
  • Décrit le scénario principal seulement

• Format informel

  • Court
  • Brève description des scénarios alternatifs

• Format étendu:

  • Très détaillé
  • Description complète du scénario principal et des scénarios alternatifs

Cas d’utilisation de haut niveau

Un exemple de cas d’utilisation pour le guichet automatique:

Use case	Effectuer un retrait
Acteur(s)	Client
Type	Primaire
Description	Un client se présente au guichet automatique, s'identifie, retire un montant d'argent et quitte avec son argent

Use Case Diagram

• Objectif: montré plusieurs "use case" sur le même diagram

• Montrer comment le système interagit avec des "agents exterieurs"

• Montrer les actions importantes

• Montrer les relations entre les actions

• Montrer les relations entre les acteurs et les actions

Briques

Use case diagram

Diagramme de cas d’utilisation (use case)

1. Après avoir identifié les requis du système, définir les frontières du système, puis identifier les acteurs et les cas d’utilisation.

2. Écrire tous les cas d’utilisation en format de haut niveau et les catégoriser comme primaires, secondaires ou optionnels.

3. Tracer un diagramme de cas d’utilisation (cas d’utilisation primaires).

4. Identifier et illustrer les relations entre les cas.

5. Écrire les cas d’utilisation les plus critiques, influents ou risqués dans un format étendu et essentiel.

6. Écrire le minimum de cas réels.

7. Ordonner les cas d’utilisation en ordre d’importance.

Diagramme de cas d’utilisation

Facile à comprendre par les utilisateurs et les développeurs.

Permet de faire un inventaire de haut niveau des exigences. Aide à détecter des exigences implicites ou oubliées.

Ce diagramme regroupe plusieurs cas d'utilisation (use cases) afin de donner une vue d'ensemble actions possibles.

Exemple pour faire un dessert...

1. Faire dessert
   1. Faire Gateau
   2. Faire Glassage

• Didier fait le gateau

• Stephanie est la comme experte

À la base

Acteurs:

• cuisinier médiocre

Systemes:

• Cuisine

Actions

• Faire Gateau
• Faire dessert
• faire glaçage

acteurs

• Représente une "catégorie de personne" pas une personne

• Peut être une personne physique, un système ou autre..

• Les acteurs sont toujours extérieur au système

Acteurs principaux

1. Initie l'intéraction avec le système
2. Placé à gauche du diagram

Acteurs secondaires

1. est réactif au système
2. Placé à droite du diagram

Interations

Interations Acteurs-Actions:

• Le cuisinier médiocre fait le dessert

Systemes:

• Cuisine

Interations Acteurs-Actions:

• Pour Faire Dessert il faut Faire Gateau
• Pour Faire Dessert il faut Faire Glacage

Ajout d'autres acteurs

À la base

Acteurs:

• cuisinier médiocre (principal)
• cuisiniere supreme (secondair)

Systemes:

• Cuisine

Actions

• Faire Gateau
• Faire dessert
• faire glaçage
• demander aide

Interations

Interations Acteurs-Actions:

• Le cuisinier médiocre fait le dessert (principal)
• La cuisiniere supreme donne de l'aide (secondair)

Systemes:

• Cuisine

Interations Acteurs-Actions:

• Pour Faire Dessert il faut Faire Gateau
• Pour Faire Dessert il faut Faire Glacage
• Faire Gateau peut utiliser Demander aide
• Faire Glacage peut utiliser Demander aide

Exercices

À partir des exigences suivantes, faites-en un diagramme de cas d’utilisation.

• Le jeu doit permettre au joueur de créer une partie
• Le joueur qui crée une partie s'y join automatiquement
• Le joueur peut quitter la partie à laquelle il joue
• Chaque joueur peut avoir une liste d'amis conservée par le jeu
• Un joueur peut ajouter un ami de la liste d'amis
• Un joueur peut enlever un ami de la liste d'amis
• Le jeur doit permetter au joueur d'inviter des amis faisant partie de sa liste d'ami à participer à une partie à laquelle il joue

Sequence diagram

Tout ce cours est un plagit flagrant d'un vidéo de 9 minutes

• https://youtu.be/pCK6prSq8aw?feature=shared

Exemple

C'est quoi un sequence diagram

Les diagrammes de séquences sont la représentation graphique des interactions entre les acteurs et le système selon un ordre chronologique

Le diagramme de séquence permet de montrer les interactions d'objets dans le cadre d'un scénario d'un diagramme des cas d'utilisation

La dimension verticale du diagramme représente le temps, permettant de visualiser l'enchaînement des actions dans le temps, et de spécifier la naissance et la mort d'objets.

Différentes parties d'un diagram en séquence

Flèches d'un diagram en séquence

Mermaid JS

• Mermaid est excellent pour les séquence diagrams

https://mermaid.js.org/syntax/sequenceDiagram.html