Mermaid diagrammen¶

Om code te kunnen documenteren is het vaak handig om diagrammen te kunnen maken. Er zijn een aantal formele manieren om de werking van code in diagrammen te kunnen weergeven. Dergelijke diagrammen kunnen met veel verschillende soorten tools worden gemaakt. Met veel van deze tools exporteer je je uiteindelijke diagram als een vector of bitmap bestand. De vorm van het diagram is dan als plaatje beschikbaar te maken in je markdown documentatie, echter, de betekenis van je diagram gaat volledig verloren.

Mermaid is een tool waarmee je diagrammen kunt tekenen met behulp van een markdown achtige taal.

Installeren¶

Er bestaat een Mermaid plugin voor de mkdocs site generator. Om deze beschikbaar te maken in je markdown site zullen er een paar aanpassingen gedaan moeten worden:

Voeg de volgende regel toe aan de file requirements.txt die je kan vinden in de root-directory van je project.

mkdocs-mermaid2-plugin ~= 0.6.0

Voeg de volgende regel toe aan de plugins sectie van je `mkdocs.yml file die je kan vinden in de root-directory van je project.

plugins:
  - search
  - mermaid2

Voeg de volgende regels toe aan de markdown_extensions sectie van je `mkdocs.yml file die je kan vinden in de root-directory van je project.

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Nu worden mermaid diagrammen die je in je markdown documentatie opneemt omgezet naar plaatjes voor op je site.

Voorbeelden¶

Class diagram¶

Een class diagram geeft de relaties aan tussen de verschillende classes in je code.

Een mermaid script voor een class diagram ziet er in je markdown bestand zo uit:

    ```mermaid
    classDiagram
        Animal <|-- Duck
        Animal <|-- Fish
        Animal <|-- Zebra
        Animal : +int age
        Animal : +String gender
        Animal: +isMammal()
        Animal: +mate()
        class Duck{
            +String beakColor
            +swim()
            +quack()
        }
        class Fish{
            -int sizeInFeet
            -canEat()
        }
        class Zebra{
            +bool is_wild
            +run()
        }
    ```

Bovenstaande diagram wordt als volgt omgezet in een plaatje:

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

Bronnen¶

Last update: December 9, 2022