diff mbox series

[v2,3/5] conf.py: support mermaid plugin

Message ID 20260924192929.907566-4-adrian.freihofer@siemens.com
State New
Headers show
Series dev-manual/devtool: ide-sdk doc rewrite and Mermaid diagrams | expand

Commit Message

Freihofer, Adrian Sept. 24, 2026, 7:29 p.m. UTC 
From: Adrian Freihofer <adrian.freihofer@siemens.com>

Add the sphinxcontrib-mermaid extension so ".mmd" Mermaid diagrams can
be included directly via the "mermaid" directive and rendered
client-side, without pre-rendering and committing image files.

This adds sphinxcontrib-mermaid as a new Pipfile/build dependency. No
other tooling (e.g. Node.js, mermaid-cli/mmdc) is required on the build
server: with the default "raw" output format, diagrams are shipped as-is
in the HTML and rendered in the reader's browser via mermaid.js, loaded
from a CDN.

Without Pipenv, a plain venv also works, e.g.:

    python3 -m venv .venv
    .venv/bin/pip install sphinx sphinx-rtd-theme sphinx-copybutton \
        sphinxcontrib-mermaid sphinxcontrib-svg2pdfconverter pyyaml

Also tweak mermaid_height and the diagram font in theme_overrides.css
to fix distorted/clipped diagram rendering.

Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
---
 documentation/Pipfile                           |  1 +
 documentation/conf.py                           |  6 ++++++
 documentation/sphinx-static/theme_overrides.css | 17 +++++++++++++++++
 3 files changed, 24 insertions(+)
diff mbox series

Patch

diff --git a/documentation/Pipfile b/documentation/Pipfile
index f415cbf3f..5fcd8b9c3 100644
--- a/documentation/Pipfile
+++ b/documentation/Pipfile
@@ -12,6 +12,7 @@  sphinx = "*"
 sphinx-rtd-theme = "*"
 pyyaml = "*"
 sphinx-copybutton = "*"
+sphinxcontrib-mermaid = "*"
 # SVG to PNG only supported since 2.0.0
 sphinxcontrib-svg2pdfconverter = ">=2.0.0"
 
diff --git a/documentation/conf.py b/documentation/conf.py
index 48d28a686..c1b418499 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -50,10 +50,16 @@  extensions = [
     'sphinx.ext.extlinks',
     'sphinx.ext.intersphinx',
     'sphinx_copybutton',
+    'sphinxcontrib.mermaid',
     'sphinxcontrib.rsvgconverter',
     'yocto-vars'
 ]
 
+# Let Mermaid diagrams keep their natural aspect ratio (based on each
+# diagram's own width/height) instead of being squeezed into the default
+# fixed 500px height, which visibly distorted/shrank taller flowcharts.
+mermaid_height = "auto"
+
 # current_version = "dev"
 # bitbake_version = "" # Leave empty for development branch
 # Obtain versions from poky.yaml instead
diff --git a/documentation/sphinx-static/theme_overrides.css b/documentation/sphinx-static/theme_overrides.css
index f9e067239..0b2be9e01 100644
--- a/documentation/sphinx-static/theme_overrides.css
+++ b/documentation/sphinx-static/theme_overrides.css
@@ -171,3 +171,20 @@  section#welcome-to-the-yocto-project-documentation p.caption {
     }
 
 }
+
+/*
+ * Mermaid diagrams are rendered inside a <pre class="mermaid"> element, so
+ * they otherwise inherit this theme's monospace "pre" font, and some of
+ * Mermaid's edge labels end up keeping their default 16px font size instead
+ * of the larger size configured in the diagrams themselves. Force a
+ * consistent, larger, non-monospace font so label text isn't clipped by a
+ * too-small measured bounding box.
+ */
+.mermaid,
+.mermaid .edgeLabel,
+.mermaid .edgeLabel p,
+.mermaid .nodeLabel,
+.mermaid .nodeLabel p {
+  font-family: Helvetica, Arial, sans-serif !important;
+  font-size: 20px !important;
+}