[PATCH 2/3] Sphinx docs: Enable autosectionlabels and Mermaid support

[Bernhard Kaindl <bernhard.kaindl@xxxxxxxxxx>]

Enable sphinx.ext.autosectionlabel which allows referencing sections
using their title, without needing to add explicit labels to each section
and enable support for Mermaid diagrams for design documents.

Signed-off-by: Bernhard Kaindl <bernhard.kaindl@xxxxxxxxxx>
---
 .readthedocs.yaml |  2 +-
 docs/conf.py      | 21 +++++++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index d3aff7662ebf..c61d5eb74107 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -12,7 +12,7 @@ build:
   jobs:
     post_install:
       # Instead of needing a separate requirements.txt
-      - python -m pip install --upgrade --no-cache-dir sphinx-rtd-theme
+      - python -m pip install --upgrade --no-cache-dir sphinx-rtd-theme 
sphinxcontrib-mermaid
 
 sphinx:
   configuration: docs/conf.py
diff --git a/docs/conf.py b/docs/conf.py
index 2fb8bafe6589..8aeab17a1a83 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -63,6 +63,27 @@ needs_sphinx = '1.4'
 # ones.
 extensions = []
 
+
+# autosectionlabel allows referencing sections using their title, without
+# needing to add explicit labels to each section. Used by design documents.
+extensions.append("sphinx.ext.autosectionlabel")
+# Setting autosectionlabel_prefix_document to True allows disambiguating
+# between sections with the same title in different documents by prefixing
+# the label with the document path.
+autosectionlabel_prefix_document = True
+
+
+# Mermaid diagrams are used in the design documents, so we try to
+# load the extension if it's available, but don't fail if it's not:
+try:
+    import sphinxcontrib.mermaid
+
+    extensions.append("sphinxcontrib.mermaid")
+    # For included Mermaid diagram files, init the extension explicitly.
+    mermaid_init_js = "mermaid.initialize({ startOnLoad: true });"
+except ImportError:
+    pass
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-- 
2.39.5