docs: add mermaid plugin and replace image

dev-docs/howtoguides/docs_diagrams.md

@@ -0,0 +1,8 @@
+# How to add a diagram to the documentation
+
+Our documentation builds are configured to allow the use of [mermaid](https://mermaid.js.org/) for diagramming, using the [sphinxcontrib-mermaid](https://github.com/mgaitan/sphinxcontrib-mermaid) plugin.
+
+These links may be helpful to get started creating a new diagram in our documentation:
+- [Syntax for adding a mermaid block to a ReStructured Text file](https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/)
+- [Syntax for adding a mermaid block to a Markdown file](https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/#markdown-support)
+- [Mermaid syntax for creating a flowchart](https://mermaid.js.org/syntax/flowchart.html?id=flowcharts-basic-syntax)

docs-requirements.txt

@@ -5,3 +5,4 @@ sphinx==5.1.1
 sphinx_autobuild
 sphinx_copybutton
 sphinx_design
+sphinxcontrib-mermaid

docs/_static/css/mermaid.css

@@ -0,0 +1,33 @@
+.mermaid {
+    display: flex;
+    justify-content: center;
+    padding-bottom: 0.5rem;
+}
+
+.mermaid .node rect,
+.mermaid .node circle,
+.mermaid .node ellipse,
+.mermaid .node polygon,
+.mermaid .node path
+{
+    fill: var(--color-background-item) !important;
+    stroke: var(--color-background-border) !important;
+}
+
+.mermaid .label text,
+.mermaid span,
+.mermaid p
+{
+    color: var(--color-content-foreground) !important;
+}
+
+.mermaid .flowchart-link
+{
+    stroke: var(--color-content-foreground) !important;
+}
+
+.mermaid .marker
+{
+    fill: var(--color-content-foreground) !important;
+    stroke: var(--color-content-foreground) !important;
+}

docs/conf.py

@@ -32,6 +32,7 @@
     "myst_parser",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinxcontrib.mermaid",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -103,6 +104,7 @@
     "css/logo.css",
     "css/github_issue_links.css",
     "css/custom.css",
+    "css/mermaid.css",
 ]
 html_js_files = [
     "js/github_issue_links.js",

docs/explanations/cves_and_usns_explained.md

@@ -33,7 +33,27 @@ A USN is composed of different CVEs. If the same CVE appears on multiple USNs, w
 In the following image, we can see a visual representation of that concept, where USN-789 and USN-321
 are related USNs because both are affected by CVE-2:
 
-![Related USN example](../images/usn-related.png)
+```{mermaid}
+graph TD;
+    %% nodes
+    usn1[USN-123]
+    usn2[USN-456]
+    usn3[USN-789]
+    usn4[USN-321]
+    usn5[USN-654]
+    cve1((CVE-1))
+    cve2((CVE-2))
+    cve3((CVE-3))
+
+    %% arrows
+    usn1-->cve1
+    usn1-->cve2
+    usn1-->cve3
+    cve1-->usn2
+    cve2-->usn3
+    cve2-->usn4
+    cve3-->usn5
+```
 
 
 A real example can be seen in [USN-5573-1](https://ubuntu.com/security/notices/USN-5573-1).