crate · amotl · Jul 21, 2023 · Jul 13, 2023 · Jul 13, 2023 · Jul 13, 2023
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -6,6 +6,9 @@ CHANGES
 Unreleased
 ----------
 
+- Add modern components from the Sphinx ecosystem: myst-parser, sphinx-design,
+  sphinx-inline-tabs, sphinx-subfigure, sphinx-togglebutton, sphinxcontrib-mermaid.
+
 
 2023/05/15 0.27.1
 -----------------

diff --git a/docs/_static/mermaid-example.mmd b/docs/_static/mermaid-example.mmd
@@ -0,0 +1,63 @@
+flowchart LR
+
+  subgraph sensors
+
+     subgraph ism
+        RF-1[RF sensor 1]
+        RF-2[RF sensor 2]
+        RF-N[RF sensor N]
+        relay{{telemetry relay}}
+     end
+     subgraph sub1ghz
+        LORAWAN[LoRaWAN sensor]
+        LORA[LoRa sensor]
+     end
+     subgraph cellular
+        CELL-GSM[GSM sensor]
+        CELL-LTE[LTE M1/NB1 sensor]
+     end
+
+     gateway{{network gateway}}
+
+     RF-1  --> relay
+     RF-2  --> relay
+     RF-N  --> relay
+     relay --> gateway
+
+     TTN{TTN}
+
+  end
+
+  subgraph network
+     HTTP{HTTP}
+     MQTT{MQTT}
+  end
+
+  subgraph backend
+
+     Kotori>Kotori message router\nand data historian]
+     InfluxDB[(InfluxDB)]
+     CrateDB[(CrateDB)]
+
+     Kotori               --> InfluxDB
+     Kotori               --> CrateDB
+     Kotori               --> Grafana
+
+  end
+
+  %% Breadboard
+
+  %% Sensors
+  LORAWAN     --> TTN
+  LORA        --> gateway
+
+  %% Network
+  gateway     --> network
+  TTN         --> network
+
+  CELL-GSM  --> network
+  CELL-LTE  --> network
+
+  %% Kotori
+  MQTT     --> Kotori
+  HTTP     --> Kotori
diff --git a/docs/_static/myst-logo-wide.png b/docs/_static/myst-logo-wide.png
diff --git a/docs/_static/myst-logo-wide.svg b/docs/_static/myst-logo-wide.svg
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,3 +20,8 @@
 html_context_custom.update({
     #"display_github": False,
 })
+
+
+intersphinx_mapping["myst"] = ("https://myst-parser.readthedocs.io/en/latest/", None)
+intersphinx_mapping["sd"] = ("https://sphinx-design.readthedocs.io/en/latest/", None)
+intersphinx_mapping["sde"] = ("https://sphinx-design-elements.readthedocs.io/en/latest/", None)
diff --git a/docs/diagrams.rst b/docs/diagrams.rst
@@ -9,3 +9,51 @@ PlantUML
 
     Alice -> Bob: Hi!
     Alice <- Bob: How are you?
+
+Mermaid
+=======
+
+.. mermaid::
+
+    flowchart LR
+
+      subgraph sensors
+
+         subgraph ism
+            RF-1[RF sensor 1]
+            RF-2[RF sensor 2]
+            RF-N[RF sensor N]
+            relay{{telemetry relay}}
+         end
+         subgraph sub1ghz
+            LORAWAN[LoRaWAN sensor]
+            LORA[LoRa sensor]
+         end
+         subgraph cellular
+            CELL-GSM[GSM sensor]
+            CELL-LTE[LTE M1/NB1 sensor]
+         end
+
+         gateway{{network gateway}}
+
+         RF-1  --> relay
+         RF-2  --> relay
+         RF-N  --> relay
+         relay --> gateway
+
+         TTN{TTN}
+
+      end
+
+      %% Breadboard
+
+      %% Sensors
+      LORAWAN     --> TTN
+      LORA        --> gateway
+
+      %% Network
+      gateway     --> network
+      TTN         --> network
+
+      CELL-GSM  --> network
+      CELL-LTE  --> network
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,41 +1,57 @@
 .. _index:
 
-==========
-Page Title
-==========
+###########################
+CrateDB documentation theme
+###########################
 
-.. meta::
-    :description lang=en:
-        This is the meta description, it should be between 150-300 characters.
-        Meta descriptions are used for display but not for ranking.
 
-This is a sample documentation project that can be used for visually testing
-the theme.
+*****
+About
+*****
 
-How to use this documentation:
+A theme component for the `Sphinx static documentation generator`_ used by
+all the Crate.io documentation projects. Examples:
 
-- Verify that each page element displays correctly. Some page elements identify
-  themselves (e.g., the :ref:`index`) and some elements describe how they ought
-  to appear (e.g., the :ref:`first admonition <first-admonition>`).
+- `CrateDB Reference`_
+- `CrateDB Python Client`_
 
-How to improve this documentation:
 
-- If you notice any bugs, please `report an issue`_ or create a PR to fix them.
+********
+Overview
+********
 
-- Add page elements and use the available text to describe how the element
-  should be displayed.
+This section outlines a few features, elements, and style-guides by example.
 
 
-.. NOTE::
+Modernized
+==========
 
-    For help building this documentation as a part of your testing and *Quality
-    Assurance* (QA) workflow, see the `developer guide`_.
+A side-by-side gallery demonstrating both reStructuredText and Markedly
+Structured Text syntax.
+
+.. grid::
+
+    .. grid-item::
+        :columns: 6
 
-.. rubric:: Table of Contents
+        .. toctree::
+            :titlesonly:
 
-.. contents::
-   :local:
+            rst/index
 
+    .. grid-item::
+        :columns: 6
+
+        .. toctree::
+            :titlesonly:
+
+            myst/index
+
+
+Legacy
+======
+
+The legacy feature gallery exclusively uses reStructuredText.
 
 .. toctree::
     :maxdepth: 1
@@ -48,10 +64,45 @@ How to improve this documentation:
     images
     diagrams
     codesnippets
-
     subpage
     glossary
 
 
+
+*******
+Details
+*******
+
+.. meta::
+    :description lang=en:
+        This is the meta description, it should be between 150-300 characters.
+        Meta descriptions are used for display but not for ranking.
+
+This is a sample documentation project that can be used for visually testing
+the theme.
+
+How to use this documentation:
+
+- Verify that each page element displays correctly. Some page elements identify
+  themselves (e.g., the :ref:`index`) and some elements describe how they ought
+  to appear (e.g., the :ref:`first admonition <first-admonition>`).
+
+How to improve this documentation:
+
+- If you notice any bugs, please `report an issue`_ or create a PR to fix them.
+
+- Add page elements and use the available text to describe how the element
+  should be displayed.
+
+
+.. NOTE::
+
+    To learn how to run sandbox or CI builds as a part of your testing and *Quality
+    Assurance* (QA) workflow, see the `developer guide`_.
+
+
+.. _CrateDB Python Client: https://crate.io/docs/python/
+.. _CrateDB Reference: https://crate.io/docs/crate/reference/
 .. _developer guide: https://github.com/crate/crate-docs-theme/blob/main/DEVELOP.rst
 .. _report an issue: https://github.com/crate/crate-docs-theme/issues/new
+.. _Sphinx static documentation generator: https://www.sphinx-doc.org/
diff --git a/docs/myst/button.md b/docs/myst/button.md
@@ -0,0 +1,20 @@
+# Buttons
+
+## Documentation
+- [sphinx{design} » Buttons](inv:sd#buttons)
+
+## Examples
+```{button-link} https://example.com
+:color: primary
+:shadow:
+```
+
+```{button-link} https://example.com
+:color: primary
+:outline:
+```
+
+```{button-link} https://example.com
+:color: secondary
+:expand:
+```
diff --git a/docs/myst/crossref.md b/docs/myst/crossref.md
@@ -0,0 +1,12 @@
+# Cross-references
+
+Being able to use cross-references appropriately, i.e. optimally linking between
+documentation resources, even across projects, is important for documentation
+authoring. Please refer to [MyST cross-references](inv:myst#syntax/referencing),
+in order to learn about how this works using the Markdown markup language.
+
+By using cross-references properly, maintenance efforts regarding broken links will
+be greatly reduced, because all target references will be validated at build time.
+See also [How to use cross-references with Sphinx].
+
+[How to use cross-references with Sphinx]: https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html
diff --git a/docs/myst/icon.md b/docs/myst/icon.md
@@ -0,0 +1,30 @@
+# Icons
+
+## Documentation
+- [sphinx{design} » Icons](inv:sd#icons)
+
+## Examples
+
+### Octicon Icons
+
+A coloured icon: {octicon}`report;1em;sd-text-info`, some more text.
+
+- Alert: {octicon}`alert`
+- Mention: {octicon}`mention`
+
+### Material Design Icons
+
+- regular icon: {material-regular}`data_exploration;2em`, some more text
+- A coloured regular icon: {material-regular}`settings;3em;sd-text-success`, some more text.
+- A coloured outline icon: {material-outlined}`settings;3em;sd-text-success`, some more text.
+- A coloured sharp icon: {material-sharp}`settings;3em;sd-text-success`, some more text.
+- A coloured round icon: {material-round}`settings;3em;sd-text-success`, some more text.
+- A coloured two-tone icon: {material-twotone}`settings;3em;sd-text-success`, some more text.
+- A fixed size icon: {material-regular}`data_exploration;24px`, some more text.
+
+### FontAwesome Icons
+
+- An icon {fas}`spinner;sd-text-primary`, some more text.
+- An icon {fab}`github`, some more text.
+- An icon {fab}`gitkraken;sd-text-success fa-xl`, some more text.
+- An icon {fas}`skull;sd-text-danger`, some more text.