From 456734f55a11a6109d3fa91ce92ec36b75a43cda Mon Sep 17 00:00:00 2001 From: Ben Deane Date: Fri, 26 Sep 2025 19:23:46 -0600 Subject: [PATCH] :books: Separate mermaid diagrams Problem: - Mermaid diagrams are inlined in documentation, which means Github does not know how to render them. Solution: - Separate mermaid docs into their own files. Github knows how to render `.mmd` files. --- docs/flows.adoc | 63 ++---------------------------------------- docs/intro.adoc | 22 +-------------- docs/library_deps.mmd | 18 ++++++++++++ docs/morning_flow1.mmd | 10 +++++++ docs/morning_flow2.mmd | 19 +++++++++++++ docs/morning_flow3.mmd | 22 +++++++++++++++ 6 files changed, 73 insertions(+), 81 deletions(-) create mode 100644 docs/library_deps.mmd create mode 100644 docs/morning_flow1.mmd create mode 100644 docs/morning_flow2.mmd create mode 100644 docs/morning_flow3.mmd diff --git a/docs/flows.adoc b/docs/flows.adoc index b58d896a..2ca88752 100644 --- a/docs/flows.adoc +++ b/docs/flows.adoc @@ -72,19 +72,7 @@ to the flow. If we only use the `morning` component in our project, the `MorningRoutine` flow graph would look like the following: -[mermaid, format="svg"] ----- -flowchart TD - a(WAKE_UP) - b(selfcare::SHOWER) - c(selfcare::GET_DRESSED) - d(food::MAKE_COFFEE) - e(food::DRINK_COFFEE) - a --> b - b --> c - c --> d - d --> e ----- +mermaid::morning_flow1.mmd[format="svg"] The power of `flow` services comes when more than one component adds actions to the flow. Flows can be extended by inserting additional actions with new @@ -114,28 +102,7 @@ struct childcare { The new steps are inserted into the existing `flow`​'s dependency graph: -[mermaid, format="svg"] ----- -flowchart TD - a(WAKE_UP) - b(selfcare::SHOWER) - c(selfcare::GET_DRESSED) - d(food::MAKE_COFFEE) - e(food::DRINK_COFFEE) - a --> b - b --> c - c --> d - d --> e - f(food::MAKE_BREAKFAST) - g(food::EAT_BREAKFAST) - h(childcare::PACK_SCHOOL_LUNCHES) - i(childcare::SEND_KIDS_TO_SCHOOL) - d --> h - h --> e - e --> f - f --> g - g --> i ----- +mermaid::morning_flow2.mmd[format="svg"] Multiple independent components can add actions to the same `flow`. This is the power of `flow` services, they can be extended by multiple independent @@ -161,31 +128,7 @@ all without the `MorningRoutine` source code having known about the new functionality. We can mix and match new components without modifying the original source code. -[mermaid, format="svg"] ----- -flowchart TD - a(WAKE_UP) - b(selfcare::SHOWER) - c(selfcare::GET_DRESSED) - d(food::MAKE_COFFEE) - e(food::DRINK_COFFEE) - a --> b - b --> c - c --> d - d --> e - f(food::MAKE_BREAKFAST) - g(food::EAT_BREAKFAST) - h(childcare::PACK_SCHOOL_LUNCHES) - i(childcare::SEND_KIDS_TO_SCHOOL) - d --> h - h --> e - e --> f - f --> g - g --> i - j(exercise::RIDE_STATIONARY_BIKE) - a --> j - j --> b ----- +mermaid::morning_flow3.mmd[format="svg"] The `cib` library will take care of initializing and building all services, including `flow` services. For `flow`​s, this means the dependency graph will be diff --git a/docs/intro.adoc b/docs/intro.adoc index d9c46402..a5e36f18 100644 --- a/docs/intro.adoc +++ b/docs/intro.adoc @@ -53,24 +53,4 @@ _cib_ contains several parts that work together: Various sub-libraries within CIB form a dependency graph. `cib` is an omnibus library that contains all the functionality. -[mermaid, format="svg"] ----- -flowchart BT - nexus(cib_nexus) - log(cib_log) - match(cib_match) - lookup(cib_lookup) - - flow(cib_flow) --> nexus - flow --> log - - log_fmt(cib_log_fmt) --> log - msg(cib_msg) --> log & match - msg --> lookup - - log_binary(cib_log_binary) --> msg - seq(cib_seq) --> flow - - interrupt(cib_interrupt) - cib --> seq & log_fmt & log_binary & interrupt ----- +mermaid::library_deps.mmd[format="svg"] diff --git a/docs/library_deps.mmd b/docs/library_deps.mmd new file mode 100644 index 00000000..8c2f1185 --- /dev/null +++ b/docs/library_deps.mmd @@ -0,0 +1,18 @@ +flowchart BT + nexus(cib_nexus) + log(cib_log) + match(cib_match) + lookup(cib_lookup) + + flow(cib_flow) --> nexus + flow --> log + + log_fmt(cib_log_fmt) --> log + msg(cib_msg) --> log & match + msg --> lookup + + log_binary(cib_log_binary) --> msg + seq(cib_seq) --> flow + + interrupt(cib_interrupt) + cib --> seq & log_fmt & log_binary & interrupt diff --git a/docs/morning_flow1.mmd b/docs/morning_flow1.mmd new file mode 100644 index 00000000..0341f577 --- /dev/null +++ b/docs/morning_flow1.mmd @@ -0,0 +1,10 @@ +flowchart TD + a(WAKE_UP) + b(selfcare::SHOWER) + c(selfcare::GET_DRESSED) + d(food::MAKE_COFFEE) + e(food::DRINK_COFFEE) + a --> b + b --> c + c --> d + d --> e diff --git a/docs/morning_flow2.mmd b/docs/morning_flow2.mmd new file mode 100644 index 00000000..5a4ce327 --- /dev/null +++ b/docs/morning_flow2.mmd @@ -0,0 +1,19 @@ +flowchart TD + a(WAKE_UP) + b(selfcare::SHOWER) + c(selfcare::GET_DRESSED) + d(food::MAKE_COFFEE) + e(food::DRINK_COFFEE) + a --> b + b --> c + c --> d + d --> e + f(food::MAKE_BREAKFAST) + g(food::EAT_BREAKFAST) + h(childcare::PACK_SCHOOL_LUNCHES) + i(childcare::SEND_KIDS_TO_SCHOOL) + d --> h + h --> e + e --> f + f --> g + g --> i diff --git a/docs/morning_flow3.mmd b/docs/morning_flow3.mmd new file mode 100644 index 00000000..e4da9420 --- /dev/null +++ b/docs/morning_flow3.mmd @@ -0,0 +1,22 @@ +flowchart TD + a(WAKE_UP) + b(selfcare::SHOWER) + c(selfcare::GET_DRESSED) + d(food::MAKE_COFFEE) + e(food::DRINK_COFFEE) + a --> b + b --> c + c --> d + d --> e + f(food::MAKE_BREAKFAST) + g(food::EAT_BREAKFAST) + h(childcare::PACK_SCHOOL_LUNCHES) + i(childcare::SEND_KIDS_TO_SCHOOL) + d --> h + h --> e + e --> f + f --> g + g --> i + j(exercise::RIDE_STATIONARY_BIKE) + a --> j + j --> b