Add dark theme and theme switcher

docs/conf.py

@@ -63,7 +63,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
 
 # -- Extension options -------------------------------------------------------
 

docs/user_guide/configuring.rst

@@ -10,7 +10,7 @@ in your ``conf.py`` file. This is a dictionary with ``key: val`` pairs that
 you can configure in various ways. This page describes the options available to you.
 
 Configure project logo
-==============================
+======================
 
 To add a logo that's placed at the left of your nav bar, put a logo file under your
 doc path's _static folder, and use the following configuration:
@@ -31,6 +31,35 @@ If you'd like it to link to another page or use an external link instead, use th
 
 .. _icon-links:
 
+Configure default theme
+=======================
+
+The theme mode can be changed by the user. By default landing on the documentation will switch the mode to ``auto``. You can specified this value to be one of ``auto``, ``dark``, ``light``.
+
+.. code-block:: python
+
+   html_context = {
+      ...
+      "default_mode": "auto"
+   }
+
+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 = {
+      ...
+      "pygment_light_style": "tango",
+      "pygment_dark_style": "native"
+   }
+
+.. danger::
+
+   The native Sphinx option `pygments_style` will be overwritten by this theme.
+
 Configure icon links
 ====================
 

docs/user_guide/customizing.rst

@@ -30,6 +30,35 @@ To add a custom stylesheet, follow these steps:
 
 When you build your documentation, this stylesheet should now be activated.
 
+.. _manage-themes:
+
+Manage themes
+=============
+
+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:
+
+.. code-block:: css
+
+    /* anything related to the light theme */
+    html[data-theme="light"] {
+
+        /* whatever you want to change */
+        background: white;
+    }
+
+    /* anything related to the dark theme */
+    html[data-theme="dark"] {
+
+        /* whatever you want to change */
+        background: black;
+    }
+
 .. _css-variables:
 
 CSS Theme variables
@@ -58,7 +87,8 @@ In order to change a variable, follow these steps:
 
    Note that these are `CSS variables <css-variable-help_>`_ and not
    `SASS variables <https://sass-lang.com/documentation/variables>`_.
-   The theme is defined with CSS variables, not SASS variables!
+   The theme is defined with CSS variables, not SASS variables! refer to the previous section if
+   you desire a differnet behaviour between the light and dark theme
 
 For a complete list of the theme variables that you may override, see the
 `theme variables defaults CSS file <pydata-css-variables_>`_:

docs/user_guide/sections.rst

@@ -138,6 +138,7 @@ will be named accordingly).
 - ``sidebar-nav-bs.html``
 - ``sphinx-version.html``
 - ``version-switcher.html``
+- ``theme-switcher.html``
 
 Add your own HTML templates to theme sections
 =============================================

src/pydata_sphinx_theme/__init__.py

@@ -10,6 +10,8 @@
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.errors import ExtensionError
 from sphinx.util import logging
+from pygments.formatters import HtmlFormatter
+from pygments.styles import get_all_styles
 
 from .bootstrap_html_translator import BootstrapHTML5Translator
 
@@ -501,6 +503,87 @@ def get_edit_url():
     context["theme_show_toc_level"] = int(context.get("theme_show_toc_level", 1))
 
 
+# ------------------------------------------------------------------------------
+# handle pygment css
+# ------------------------------------------------------------------------------
+
+# inspired by the Furo theme
+# https://github.com/pradyunsg/furo/blob/main/src/furo/__init__.py
+
+
+def _get_styles(formatter, prefix):
+    """
+    Get styles out of a formatter, where everything has the correct prefix.
+    """
+
+    for line in formatter.get_linenos_style_defs():
+        yield f"{prefix} {line}"
+    yield from formatter.get_background_style_defs(prefix)
+    yield from formatter.get_token_style_defs(prefix)
+
+
+def get_pygments_stylesheet(light_style, dark_style):
+    """
+    Generate the theme-specific pygments.css.
+    There is no way to tell Sphinx how the theme handles modes
+    """
+    light_formatter = HtmlFormatter(style=light_style)
+    dark_formatter = HtmlFormatter(style=dark_style)
+
+    lines = []
+
+    light_prefix = 'html[data-theme="light"] .highlight'
+    lines.extend(_get_styles(light_formatter, prefix=light_prefix))
+
+    dark_prefix = 'html[data-theme="dark"] .highlight'
+    lines.extend(_get_styles(dark_formatter, prefix=dark_prefix))
+
+    return "\n".join(lines)
+
+
+def _overwrite_pygments_css(app, exception=None):
+    """
+    Sphinx is not build to host multiple sphinx formatter and there is no way
+    to tell which one to use and when.
+    So yes, at build time we overwrite the pygment.css file so that it embeds
+    2 versions:
+    - the light theme prefixed with "[data-theme="light"]" using tango
+    - the dark theme prefixed with "[data-theme="dark"]" using native
+
+    When the theme is switched, Pygments will be using one of the preset css
+    style.
+    """
+    default_light_theme = "tango"
+    default_dark_theme = "native"
+
+    if exception is not None:
+        return
+
+    assert app.builder
+
+    # check the theme specified in the theme options
+    theme_options = app.config["html_theme_options"]
+    pygments_styles = list(get_all_styles())
+    light_theme = theme_options.get("pygment_light_style", default_light_theme)
+    if light_theme not in pygments_styles:
+        logger.warn(
+            f"{light_theme}, is not part of the available pygments style,"
+            f' defaulting to "{default_light_theme}".'
+        )
+        light_theme = default_light_theme
+    dark_theme = theme_options.get("pygment_dark_style", default_dark_theme)
+    if dark_theme not in pygments_styles:
+        logger.warn(
+            f"{dark_theme}, is not part of the available pygments style,"
+            f' defaulting to "{default_dark_theme}".'
+        )
+        dark_theme = default_dark_theme
+
+    pygment_css = Path(app.builder.outdir) / "_static" / "pygments.css"
+    with pygment_css.open("w") as f:
+        f.write(get_pygments_stylesheet(light_theme, dark_theme))
+
+
 # -----------------------------------------------------------------------------
 
 
@@ -521,6 +604,7 @@ def setup(app):
     app.connect("html-page-context", setup_edit_url)
     app.connect("html-page-context", add_toctree_functions)
     app.connect("html-page-context", update_templates)
+    app.connect("build-finished", _overwrite_pygments_css)
 
     # Include templates for sidebar
     app.config.templates_path.append(str(theme_path / "_templates"))

src/pydata_sphinx_theme/assets/scripts/index.js

@@ -9,6 +9,89 @@ import "bootstrap";
 
 import "../styles/index.scss";
 
+/*******************************************************************************
+ * Theme interaction
+ */
+
+var prefersDark = window.matchMedia("(prefers-color-scheme: dark)");
+
+/**
+ * set the the body theme to the one specified by the user browser
+ * @param {event} e
+ */
+function autoTheme(e) {
+  document.documentElement.dataset.theme = prefersDark.matches
+    ? "dark"
+    : "light";
+}
+
+/**
+ * Set the theme using the specified mode.
+ * It can be one of ["auto", "dark", "light"]
+ * @param {str} mode
+ */
+function setTheme(mode) {
+  if (mode !== "light" && mode !== "dark" && mode !== "auto") {
+    console.error(`Got invalid theme mode: ${mode}. Resetting to auto.`);
+    mode = "auto";
+  }
+
+  // get the theme
+  var colorScheme = prefersDark.matches ? "dark" : "light";
+  document.documentElement.dataset.mode = mode;
+  var theme = mode == "auto" ? colorScheme : mode;
+  document.documentElement.dataset.theme = theme;
+
+  // save mode and theme
+  localStorage.setItem("mode", mode);
+  localStorage.setItem("theme", theme);
+  console.log(`Changed to ${mode} mode using the ${theme} theme.`);
+
+  // add a listener if set on auto
+  prefersDark.onchange = mode == "auto" ? autoTheme : "";
+}
+
+/**
+ * Change the theme option order so that clicking on the btn is always a change
+ * from "auto"
+ */
+function cycleMode() {
+  const defaultMode = document.documentElement.dataset.defaultMode || "auto";
+  const currentMode = localStorage.getItem("mode") || defaultMode;
+
+  var loopArray = (arr, current) => {
+    var nextPosition = arr.indexOf(current) + 1;
+    if (nextPosition === arr.length) {
+      nextPosition = 0;
+    }
+    return arr[nextPosition];
+  };
+
+  // make sure the next theme after auto is always a change
+  var modeList = prefersDark.matches
+    ? ["auto", "light", "dark"]
+    : ["auto", "dark", "light"];
+  var newMode = loopArray(modeList, currentMode);
+  setTheme(newMode);
+}
+
+/**
+ * add the theme listener on the btns of the navbar
+ */
+function addModeListener() {
+  // the theme was set a first time using the initial mini-script
+  // running setMode will ensure the use of the dark mode if auto is selected
+  setTheme(document.documentElement.dataset.mode);
+
+  // Attach event handlers for toggling themes colors
+  const btn = document.getElementById("theme-switch");
+  btn.addEventListener("click", cycleMode);
+}
+
+/*******************************************************************************
+ * TOC interactivity
+ */
+
 function addTOCInteractivity() {
   // TOC sidebar - add "active" class to parent list
   //
@@ -31,6 +114,10 @@ function addTOCInteractivity() {
   });
 }
 
+/*******************************************************************************
+ * Scroll
+ */
+
 // Navigation sidebar scrolling to active page
 function scrollToActive() {
   var sidebar = document.querySelector("div.bd-sidebar");
@@ -73,5 +160,6 @@ function scrollToActive() {
 
 // This is equivalent to the .ready() function as described in
 // https://api.jquery.com/ready/
+$(addModeListener);
 $(scrollToActive);
 $(addTOCInteractivity);