From 588e056699c6180de8d187a7fc4712cd27deedd7 Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Thu, 26 Oct 2023 08:40:33 +0100 Subject: [PATCH] Add mdbook-mermaid (#26426) --- .github/workflows/docs.yml | 4 +- .gitignore | 2 + book.toml | 6 ++ docs/app-load.md | 137 +++++++++++++++++++++---------------- 4 files changed, 88 insertions(+), 61 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 38435d1cdb..0ce7998f44 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -47,8 +47,8 @@ jobs: with: mdbook-version: "0.4.10" - - name: Install mdbook-combiner - run: cargo install mdbook-combiner + - name: Install mdbook extensions + run: cargo install mdbook-combiner mdbook-mermaid - name: Prepare docs run: | diff --git a/.gitignore b/.gitignore index 3d737137ce..2d157538e4 100644 --- a/.gitignore +++ b/.gitignore @@ -28,3 +28,5 @@ electron/pub /src/modules.ts /build_config.yaml /book +/mermaid* +/index.html diff --git a/book.toml b/book.toml index 24275dc61c..e37b56a8d4 100644 --- a/book.toml +++ b/book.toml @@ -24,3 +24,9 @@ git-repository-url = "https://github.com/vector-im/element-web" # The path that the docs are hosted on site-url = "/element-web/" +additional-js = ["mermaid.min.js", "mermaid-init.js"] + +[preprocessor] + +[preprocessor.mermaid] +command = "mdbook-mermaid" diff --git a/docs/app-load.md b/docs/app-load.md index 6f137bc888..849e95cb8d 100644 --- a/docs/app-load.md +++ b/docs/app-load.md @@ -4,78 +4,67 @@ been kept untouched for posterity. Old slow flow: -![image](https://user-images.githubusercontent.com/2403652/73848963-00a2a080-4821-11ea-97d4-1200fc2638f3.png) + +```mermaid +flowchart TD + A1(((load_modernizr))) --> B + A2((rageshake)) --> B + B(((skin))) --> C + C(((olm))) --> D + D{mobile} --> E + E((config)) --> F + F((i18n)) --> G + style F stroke:lime + G(((theme))) --> H + H(((modernizr))) --> app + style H stroke:red +``` Current more parallel flow: -![image](https://user-images.githubusercontent.com/2403652/83146440-303a2900-a0ee-11ea-806b-4f53f039b957.png) -
Code -

-


-digraph G {
-  node [shape=box];
+```mermaid
+flowchart TD
+    subgraph index.ts
+        style index.ts stroke:orange
 
-subgraph cluster_0 {
-color=orange;
-node [style=filled];
-label = "index.ts";
+        A[/rageshake/] --> B{mobile}
+        B-- No -->C1(.)
+        B-- Yes -->C2((redirect))
+        C1 --> D[/olm/] --> R
+        C1 --> E[platform] --> F[/config/]
+        F --> G1[/skin/]
+        F --> R
+        G1 --> H
+        G1 --> R
+        F --> G2[/theme/]
+        G2 --> H
+        G2 --> R
+        F --> G3[/i18n/]
+        G3 --> H
+        G3 --> R
+        H{modernizr}-- No --> J((incompatible))-- user ignore --> R
+        H-- Yes --> R
 
-    entrypoint, s0, ready [shape=point];
-    rageshake, config, i18n, theme, skin, olm [shape=parallelogram];
-    mobile [shape=diamond, label="mobile"];
-    modernizr [shape=diamond];
-    redirect, incompatible [shape=egg];
+        linkStyle 0,7,9,11,12,14,15 stroke:blue;
+        linkStyle 4,8,10,13,16 stroke:red;
+    end
 
-    entrypoint -> rageshake;
-    rageshake -> mobile [color=blue];
-    mobile -> s0 [label="No"];
-    mobile -> redirect [label="Yes"];
+    R>ready] --> 2A
+    style R stroke:gray
 
-    s0 -> platform;
-    s0 -> olm;
-    platform -> config;
+    subgraph init.tsx
+        style init.tsx stroke:lime
+        2A[loadApp] --> 2B[matrixchat]
+    end
 
-    config -> i18n [color=blue];
-    config -> theme [color=blue];
-    config -> skin [color=blue];
-
-    i18n -> modernizr [color=blue];
-    theme -> modernizr [color=blue];
-    skin -> modernizr [color=blue];
-
-    modernizr -> ready [label="Yes"];
-    modernizr -> incompatible [label="No"];
-    incompatible -> ready [label="user ignore"];
-
-    olm -> ready [color=red];
-    config -> ready [color=red];
-    skin -> ready [color=red];
-    theme -> ready [color=red];
-    i18n -> ready [color=red];
-
-}
-
-subgraph cluster_1 {
-color = green;
-node [style=filled];
-label = "init.tsx";
-
-    ready -> loadApp;
-    loadApp -> matrixchat;
-
-}
-}
-
- -

-
+``` Key: - Parallelogram: async/await task - Box: sync task - Diamond: conditional branch -- Egg: user interaction +- Circle: user interaction - Blue arrow: async task is allowed to settle but allowed to fail - Red arrow: async task success is asserted @@ -86,4 +75,34 @@ Notes: - Everything is awaited to be settled before the Modernizr check, to allow it to make use of things like i18n if they are successful. Underlying dependencies: -![image](https://user-images.githubusercontent.com/2403652/73848977-08624500-4821-11ea-9830-bb0317c41086.png) + +```mermaid +flowchart TD + A((rageshake)) + B{mobile} + C((config)) + D(((olm))) + E((i18n)) + F(((load_modernizr))) + G(((modernizr))) + H(((skin))) + I(((theme))) + X[app] + + A --> G + A --> B + A-- assert -->X + F --> G --> X + G --> H --> X + C --> I --> X + C --> E --> X + E --> G + B --> C-- assert -->X + B --> D --> X + + style X stroke:red + style G stroke:red + style E stroke:lime + linkStyle 0,11 stroke:yellow; + linkStyle 2,13 stroke:red; +```