feat: add mermaid.js support (#1302)

* chore: add diagrams

* docs: improve example

* chore: add mermaid by default

docs/source/examples/diagrams.rst

@@ -0,0 +1,24 @@
+Diagrams 
+========
+
+The documentation toolchain supports rendering diagrams and charts using `Mermaid <https://mermaid.js.org/intro/>`_, a library designed for creating sequence diagrams, flowcharts, and other visualizations.
+
+Using:
+
+.. code-block:: python
+
+   .. mermaid ::
+
+      graph TD
+      A --> B
+      B -- Label --> C
+
+Renders:
+
+.. mermaid ::
+
+   graph TD
+   A --> B
+   B -- Label --> C
+
+For more details, refer to the `sphinxcontrib-mermaid <https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/>`_ documentation.

docs/source/examples/index.rst

@@ -16,6 +16,7 @@ In general, there are main components to the markup of any document:
    admonitions
    collapse
    code-blocks
+   diagrams
    glossary
    headings
    hero-box
@@ -44,6 +45,7 @@ In general, there are main components to the markup of any document:
   * :doc:`Admonitions <admonitions>`
   * :doc:`Collapse <collapse>`
   * :doc:`Code blocks <code-blocks>`
+  * :doc:`Diagrams <diagrams>`
   * :doc:`Glossary <glossary>`
   * :doc:`Headings <headings>`
   * :doc:`Hero box <hero-box>`

pyproject.toml

@@ -16,6 +16,7 @@ pyyaml = "^6.0.1"
 Sphinx-Substitution-Extensions = ">=2022.2.16,<2025.0.0"
 sphinx-notfound-page = "^1.0.4"
 setuptools = ">=70.1.1,<76.0.0"
+sphinxcontrib-mermaid = "^1.0.0"
 
 [tool.poetry.dev-dependencies]
 pytest = "^8.3.2"

sphinx_scylladb_theme/__init__.py

@@ -3,6 +3,7 @@
 import sphinx_collapse
 import sphinx_copybutton
 import sphinx_substitution_extensions
+from sphinxcontrib import mermaid
 from notfound import extension as not_found
 from sphinx_tabs import tabs
 
@@ -102,6 +103,7 @@ def setup(app):
 
     """Setup thid-party extensions"""
     not_found.setup(app)
+    mermaid.setup(app)
     sphinx_collapse.setup(app)
     sphinx_copybutton.setup(app)
     sphinx_substitution_extensions.setup(app)