From cc1f7bb2a7ec4b460e601b63605a7494c1ee5511 Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Wed, 14 May 2025 15:18:54 +0100 Subject: [PATCH 1/3] Added Mermaid graphical markup extension to Sphinx --- doc/Editing-the-Wiki.md | 35 +++++++++++++++++++++++++++++++++++ doc/conf.py | 4 ++++ pyproject.toml | 1 + 3 files changed, 40 insertions(+) diff --git a/doc/Editing-the-Wiki.md b/doc/Editing-the-Wiki.md index 9e159b181..e3c32fd1d 100644 --- a/doc/Editing-the-Wiki.md +++ b/doc/Editing-the-Wiki.md @@ -100,6 +100,41 @@ You can then add the image in markdown using the URL `test.png`: ![alternative text](test.png) +## Mermaid Diagrams +Mermaid diagrams can be added using the following syntax (example): +``` +```{mermaid} +--- +title: Simple sample +--- +stateDiagram-v2 + [*] --> Document + Develop_software --> Document + Document --> Develop_software + Develop_software --> Test_software + Test_software --> Crash + Crash --> Develop_software + Test_software --> [*] +``` + +will render as: +```{mermaid} +--- +title: Simple sample +--- +stateDiagram-v2 + [*] --> Document + Document --> Develop_software + Develop_software --> Document + Develop_software --> Test_software + Test_software --> Crash + Crash --> Develop_software + Test_software --> [*] +``` + + +The Mermaid syntax is documented [here](https://mermaid.js.org/intro/syntax-reference.html). + ## Spellchecking The wiki has a built-in spellchecker, which will automatically run when a commit diff --git a/doc/conf.py b/doc/conf.py index 14a46339d..7b443f010 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -41,6 +41,10 @@ "sphinx.ext.viewcode", # Redirects "sphinx_reredirects", + # Mermaid diagrams + "sphinxcontrib.mermaid", + # Graphvis diagrams + "sphinx.ext.graphviz", ] napoleon_google_docstring = True napoleon_numpy_docstring = False diff --git a/pyproject.toml b/pyproject.toml index 2af204be2..35f6443af 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -32,6 +32,7 @@ dependencies = [ "sphinxcontrib-spelling", "sphinx-reredirects", "pytest", + "sphinxcontrib-mermaid" ] [project.optional-dependencies] From 8353e57bab0b5d46684a3a16993bf6567c6470e0 Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Wed, 14 May 2025 15:20:59 +0100 Subject: [PATCH 2/3] Removed config for failed attempts to incorporate Graphvis into Sphinx at same time as Mermaid --- doc/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 7b443f010..b56701442 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -43,8 +43,6 @@ "sphinx_reredirects", # Mermaid diagrams "sphinxcontrib.mermaid", - # Graphvis diagrams - "sphinx.ext.graphviz", ] napoleon_google_docstring = True napoleon_numpy_docstring = False From f8c16f6799b57390a67ad6d7cbc938aff72e0d68 Mon Sep 17 00:00:00 2001 From: Ian Gillingham Date: Wed, 14 May 2025 15:58:04 +0100 Subject: [PATCH 3/3] Enabled zooming in Mermaid daigrams. Fixed missing closing backticks in Mermaid example in Editing-the-Wiki.md. --- doc/Editing-the-Wiki.md | 3 ++- doc/conf.py | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/Editing-the-Wiki.md b/doc/Editing-the-Wiki.md index e3c32fd1d..345ffddd5 100644 --- a/doc/Editing-the-Wiki.md +++ b/doc/Editing-the-Wiki.md @@ -102,7 +102,7 @@ You can then add the image in markdown using the URL `test.png`: ## Mermaid Diagrams Mermaid diagrams can be added using the following syntax (example): -``` +```` ```{mermaid} --- title: Simple sample @@ -116,6 +116,7 @@ stateDiagram-v2 Crash --> Develop_software Test_software --> [*] ``` +```` will render as: ```{mermaid} diff --git a/doc/conf.py b/doc/conf.py index b56701442..a3c856cfd 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -44,6 +44,7 @@ # Mermaid diagrams "sphinxcontrib.mermaid", ] +mermaid_d3_zoom = True napoleon_google_docstring = True napoleon_numpy_docstring = False