DOC: Document helper for dark mode

docs/user_guide/configuring.rst

@@ -43,14 +43,16 @@ The theme mode can be changed by the user. By default landing on the documentati
       "default_mode": "auto"
    }
 
+For more information, see :ref:`manage-themes`.
+
 Configure pygment theme
 =======================
 
 As the Sphinx theme supports multiple modes, the code highlighting colors can be modified for each one of them by modifying the `pygment_light_style`and `pygment_style_style`. You can check available Pygments colors on this `page <https://help.farbox.com/pygments.html>`__.
 
 .. code-block:: python
 
-   html_contexts = {
+   html_context = {
       ...
       "pygment_light_style": "tango",
       "pygment_dark_style": "native"

docs/user_guide/customizing.rst

@@ -39,20 +39,26 @@ When you build your documentation, this stylesheet should now be activated.
 
 .. _manage-themes:
 
-Manage themes
-=============
+Manage light and dark themes
+============================
+
+You can change the major background / foreground colors of this theme according to "dark" and "light" modes.
+These are controlled by a button in the navigation header, with the following options:
+
+- A ``light`` theme with a bright background and dark text / UI elements
+- A ``dark`` theme with a dark background and light text / UI elements
+- ``auto``: the documentation theme will follow the system default that you have set
+
+Customize the CSS of light and dark themes
+------------------------------------------
 
 .. danger::
 
     Theming is still a beta feature so the variables related to the theme switch are likely to change in the future. No backward compatibily is guaranteed when customization is done.
 
-Pydata sphinx theme embed 3 different theming mode:
 
-- ``auto``: the documentation theme will follow the one provided by your computer
-- ``dark``: the documentation is displayed with the dark theme
-- ``light``: the documentation is displayed with the light theme
-
-In order to customize the display of any of the theme element you need to encaspulate your modifications in the approriate css rules:
+To customize the CSS of page elements in a theme-dependent manner, use the ``html[data-theme='<THEME>']`` CSS selector.
+For example to define a different background color for both the light and dark themes:
 
 .. code-block:: css
 
@@ -72,6 +78,34 @@ In order to customize the display of any of the theme element you need to encasp
 
 A complete list of the used colors for this theme can be found in the `pydata default css colors file <pydata-css-colors_>`__.
 
+Define custom JavaScript to react to theme changes
+--------------------------------------------------
+
+You can define a JavaScript event hook that will run your code any time the theme changes.
+This is useful if you need to change elements of your page that cannot be defined by CSS rules.
+For example, to change an image source (e.g., logo) whenever the ``data-theme`` changes, a snippet like this can be used:
+
+.. code-block:: rst
+
+  .. raw:: html
+
+    <script type="text/javascript">
+      var observer = new MutationObserver(function(mutations) {
+        const dark = document.documentElement.dataset.theme == 'dark';
+        document.getElementsByClassName('mainlogo')[0].src = dark ? '_static/my_logo_dark.svg' : "_static/my_logo_light.svg";
+      })
+      observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
+    </script>
+    <link rel="preload" href="_static/my_logo_dark.svg" as="image">
+
+  .. image:: _static/my_logo_light.svg
+     :alt: My Logo
+     :class: logo, mainlogo
+     :align: center
+
+The JavaScript reacts to ``data-theme`` changes to alter ``img``, and the ``link`` is used to preload the dark image.
+See the `MutationObserver documentation <https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver>`_ for more information.
+
 .. _css-variables:
 
 CSS Theme variables