docs: Fix Mermaid diagrams Bug: 534320984 Change-Id: Ibd6c640d23a26ce70674336aeb1a3afd1dfaf1ec Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/435433
diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 23dbb7d..40c0a8a 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py
@@ -253,16 +253,14 @@ # https://sphinx-sitemap.readthedocs.io/en/latest/advanced-configuration.html sitemap_url_scheme = '{link}' -mermaid_init_js = ''' -mermaid.initialize({ - // Mermaid is manually started in //docs/sphinx/_static/js/pigweed.js. - startOnLoad: false, - // sequenceDiagram Note text alignment - noteAlign: "left", - // Set mermaid theme to the current furo theme - theme: localStorage.getItem("theme") == "dark" ? "dark" : "default" -}); -''' +# Mermaid style API is very hard to use and full of footguns. The `neutral` +# theme is the only readable default option on both light and dark themes. +mermaid_light_theme = 'neutral' +mermaid_dark_theme = 'neutral' +# Manually start Mermaid in //docs/sphinx/_static/js/pigweed.js to ensure +# that Mermaid does not interfere with the logic that scrolls the current +# page into view in "Section Navigation". +mermaid_init_config = {'startOnLoad': False} # Output file base name for HTML help builder. htmlhelp_basename = 'Pigweeddoc'
diff --git a/pw_build/project_builder.rst b/pw_build/project_builder.rst index 0c659eb..ea8c636 100644 --- a/pw_build/project_builder.rst +++ b/pw_build/project_builder.rst
@@ -68,7 +68,14 @@ function starts executing commands. This function allows specifying the number of parallel workers (the number of recipes which are executed in parallel). +.. raw:: html + + <style> + #arch > svg { height: 350px; } + </style> + .. mermaid:: + :name: arch flowchart TB subgraph BuildRecipeA ["<strong>BuildRecipe</strong>: ninja"]
diff --git a/pw_persistent_ram/docs.rst b/pw_persistent_ram/docs.rst index 2ad8d21..10ed8cb 100644 --- a/pw_persistent_ram/docs.rst +++ b/pw_persistent_ram/docs.rst
@@ -25,7 +25,14 @@ for managing persistent RAM, particularly in scenarios involving crash data capture and retrieval: +.. raw:: html + + <style> + #lifecycle > svg { height: 1000px; } + </style> + .. mermaid:: + :name: lifecycle graph TD DB[Device Boot]
diff --git a/pw_software_update/design.rst b/pw_software_update/design.rst index bab8fca..0a65868 100644 --- a/pw_software_update/design.rst +++ b/pw_software_update/design.rst
@@ -22,7 +22,7 @@ .. mermaid:: - flowchart LR + flowchart TB A[/Source/] --> |Build| B[/Target files/] B --> |Assemble & Sign| C[(Update bundle)] C --> |Publish| D[(Available updates)] @@ -56,7 +56,7 @@ .. mermaid:: - flowchart LR + flowchart TB A[Verified boot] --> |Embed & Verify| B[/Root key/] B --> |Delegate & Rotate| C[/Targets key/] C --> |Sign| D[/Target files/]
diff --git a/pw_tokenizer/detokenization.rst b/pw_tokenizer/detokenization.rst index b479a57..c46893c 100644 --- a/pw_tokenizer/detokenization.rst +++ b/pw_tokenizer/detokenization.rst
@@ -212,32 +212,39 @@ The following diagram describes the decoding process for optionally tokenized fields in detail. +.. raw:: html + + <style> + #decodeprocess > svg { height: 1000px; } + </style> + .. mermaid:: + :name: decodeprocess - flowchart TD - start([Received bytes]) --> binary + flowchart TD + start([Received bytes]) --> binary - binary[Decode as<br>binary tokenized] --> binary_ok - binary_ok{Detokenizes<br>successfully?} -->|no| utf8 - binary_ok -->|yes| done_binary([Display decoded binary]) + binary[Decode as<br>binary tokenized] --> binary_ok + binary_ok{Detokenizes<br>successfully?} -->|no| utf8 + binary_ok -->|yes| done_binary([Display decoded binary]) - utf8[Decode as UTF-8] --> utf8_ok - utf8_ok{Valid UTF-8?} -->|no| base64_encode - utf8_ok -->|yes| base64 + utf8[Decode as UTF-8] --> utf8_ok + utf8_ok{Valid UTF-8?} -->|no| base64_encode + utf8_ok -->|yes| base64 - base64_encode[Encode as<br>tokenized Base64] --> display - display([Display encoded Base64]) + base64_encode[Encode as<br>tokenized Base64] --> display + display([Display encoded Base64]) - base64[Decode as<br>Base64 tokenized] --> base64_ok + base64[Decode as<br>Base64 tokenized] --> base64_ok - base64_ok{Fully<br>or partially<br>detokenized?} -->|no| is_plain_text - base64_ok -->|yes| base64_results + base64_ok{Fully<br>or partially<br>detokenized?} -->|no| is_plain_text + base64_ok -->|yes| base64_results - is_plain_text{Text is<br>printable?} -->|no| base64_encode - is_plain_text-->|yes| plain_text + is_plain_text{Text is<br>printable?} -->|no| base64_encode + is_plain_text-->|yes| plain_text - base64_results([Display decoded Base64]) - plain_text([Display text]) + base64_results([Display decoded Base64]) + plain_text([Display text]) Potential decoding problems ---------------------------
diff --git a/pw_tokenizer/docs.rst b/pw_tokenizer/docs.rst index dc4adca..ececf0e 100644 --- a/pw_tokenizer/docs.rst +++ b/pw_tokenizer/docs.rst
@@ -74,26 +74,40 @@ and send the same logging information using significantly less resources: -.. mermaid:: +.. raw:: html - flowchart TD + <style> + #example > svg { height: 750px; } + </style> + +.. mermaid:: + :name: example + + %%{init: { + 'flowchart': { + 'subGraphTitleMargin': {'bottom': 15} + } + }}%% + + flowchart LR subgraph after["After: Tokenized Logs (37 bytes saved!)"] - after_log["LOG(#quot;Battery Voltage: %d mV#quot;, voltage)"] -- 4 bytes stored on-device as... --> - after_encoding["d9 28 47 8e"] -- 6 bytes sent over the wire as... --> - after_transmission["d9 28 47 8e aa 3e"] -- Displayed in logs as... --> + direction TB + after_log["LOG(#quot;Battery Voltage: %d mV#quot;, voltage)"] -- 4 bytes stored on-device as… --> + after_encoding["d9 28 47 8e"] -- 6 bytes sent over the wire as… --> + after_transmission["d9 28 47 8e aa 3e"] -- Displayed in logs as… --> after_display["#quot;Battery Voltage: 3989 mV#quot;"] end subgraph before["Before: No Tokenization"] - before_log["LOG(#quot;Battery Voltage: %d mV#quot;, voltage)"] -- 41 bytes stored on-device as... --> - before_encoding["#quot;Battery Voltage: %d mV#quot;"] -- 43 bytes sent over the wire as... --> - before_transmission["#quot;Battery Voltage: 3989 mV#quot;"] -- Displayed in logs as... --> + direction TB + before_log["LOG(#quot;Battery Voltage: %d mV#quot;, voltage)"] -- 41 bytes stored on-device as… --> + before_encoding["#quot;Battery Voltage: %d mV#quot;"] -- 43 bytes sent over the wire as… --> + before_transmission["#quot;Battery Voltage: 3989 mV#quot;"] -- Displayed in logs as… --> before_display["#quot;Battery Voltage: 3989 mV#quot;"] end - style after stroke:#00c852,stroke-width:3px - style before stroke:#ff5252,stroke-width:3px + before ~~~ after A quick overview of how the tokenized version works: