doc: fix dark mode "flashing" on page load

This hooks up the dark-mode-toggle-stylesheets-loader so that the dark
mode styles are loaded immediately, rather than waiting for the page to
load and then switching to dark mode. This prevents the "flashing" of
light mode styles on page load.

Fixes #79791

Signed-off-by: Benjamin Cabé <[email protected]>

Author: kartben

doc/_templates/layout.html

@@ -28,7 +28,14 @@
 {% endblock %}
 {% block extrahead %}
   <meta name="color-scheme" content="dark light">
-  {# Light/Dark stylesheets added here due to https://github.com/readthedocs/sphinx_rtd_theme/issues/1100 #}
-  <link rel="stylesheet" href="{{ pathto('_static/css/light.css', 1) }}" type="text/css" media="(prefers-color-scheme: light)"/>
-  <link rel="stylesheet" href="{{ pathto('_static/css/dark.css', 1) }}" type="text/css" media="(prefers-color-scheme: dark)"/>
+  {# Use dark mode loader script to prevent "flashing" of the page on load.
+     As we need a <noscript> tag and very specific orderding of the tags, this can't be done via
+     the usual add_js_file()/add_css_file() Sphinx API.
+     See https://github.com/GoogleChromeLabs/dark-mode-toggle/issues/77 #}
+  <noscript id="dark-mode-toggle-stylesheets">
+    <link rel="stylesheet" href="{{ pathto('_static/css/light.css', 1) }}" type="text/css" media="(prefers-color-scheme: light)"/>
+    <link rel="stylesheet" href="{{ pathto('_static/css/dark.css', 1) }}" type="text/css" media="(prefers-color-scheme: dark)"/>
+  </noscript>
+  <script src="{{ pathto('_static/js/dark-mode-toggle-stylesheets-loader.min.js', 1) }}"></script>
+  <script type="module" src="{{ pathto('_static/js/dark-mode-toggle.min.mjs', 1) }}"></script>
 {% endblock %}

doc/conf.py

@@ -354,4 +354,3 @@ def setup(app):
     # theme customizations
     app.add_css_file("css/custom.css")
     app.add_js_file("js/custom.js")
-    app.add_js_file("js/dark-mode-toggle.min.mjs", type="module")