docs: Use better aligned colors for dark mode

docs/_static/stdgpu_custom_sphinx.css

@@ -10,12 +10,24 @@ footer.bd-footer {
 }
 
 
-/* Better separator color in dark mode */
+/* Better aligned colors for dark mode (similar contrast to light mode) */
 html[data-theme="dark"] {
-    --pst-color-border: #38393b;
-    --pst-color-background: #151617; /* Doxygen Awesome: #1c1d1f */
+    --pst-color-border: #3a3a3a;
 }
 
+
+/* Use sphinx-book-theme separator color */
 footer.bd-footer-content {
     border-top: 1px solid var(--pst-color-border);
-}
+}
+
+.table {
+    --bs-table-border-color: var(--pst-color-border);
+}
+
+
+/* Use sphinx-book-theme separator color in sphinx-design */
+:root {
+    --sd-color-tabs-overline: var(--pst-color-border) !important;
+    --sd-color-tabs-underline: var(--pst-color-border) !important;
+}

docs/conf.py

@@ -21,10 +21,18 @@
 extensions = [
     "sphinx.ext.githubpages",
     "sphinx_copybutton",
+    "sphinx_design",
+    "sphinx_togglebutton",
     "sphinxcontrib.doxylink",
     "myst_parser",
 ]
 
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+myst_heading_anchors = 3
+
 doxylink = {
     "stdgpu": (str(pathlib.Path(__file__).parent / "doxygen" / "tagfile.xml"), "doxygen"),
 }

docs/requirements.txt

@@ -1,6 +1,8 @@
 sphinx
 sphinx-book-theme~=1.0.1
 sphinx_copybutton
+sphinx-design
+sphinx-togglebutton
 sphinxcontrib-doxylink
 doxysphinx
 myst-parser

tools/dev/color_contrast.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import skimage.color
+import numpy as np
+
+
+def contrast(rgb1, rgb2) -> float:
+    xyz1 = skimage.color.rgb2xyz(np.array(rgb1) / 255)
+    xyz2 = skimage.color.rgb2xyz(np.array(rgb2) / 255)
+
+    l1 = max(xyz1[1], xyz2[1])
+    l2 = min(xyz1[1], xyz2[1])
+
+    return (l1 + 0.05) / (l2 + 0.05)
+
+
+def main() -> None:
+    # Sphinx book theme
+    light_background = (255, 255, 255)
+    light_text = (50, 50, 50)
+    light_header = (100, 100, 100)
+    light_separator = (201, 201, 201)
+
+    # Modified Sphinx book theme (with original values if changed)
+    dark_background = (18, 18, 18)
+    dark_text = (206, 206, 206)
+    dark_header = (166, 166, 166)
+    dark_separator = (58, 58, 58)  # (192, 192, 192)
+
+    print("Light:", f"{contrast(light_background, light_text):.3f}",
+                    f"{contrast(light_background, light_header):.3f}",
+                    f"{contrast(light_background, light_separator):.3f}",
+                    f"{contrast(light_separator, light_text):.3f}",
+                    f"{contrast(light_separator, light_header):.3f}")
+
+    print("Dark: ", f"{contrast(dark_background, dark_text):.3f}",
+                    f"{contrast(dark_background, dark_header):.3f}",
+                    f"{contrast(dark_background, dark_separator):.3f}",
+                    f"{contrast(dark_separator, dark_text):.3f}",
+                    f"{contrast(dark_separator, dark_header):.3f}")
+
+
+if __name__ == "__main__":
+    main()