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,18 @@ 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 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 */
+    body[data-theme="light"] {
+
+        /* whatever you want to change */
+        background: white;
+    }
+
+    /* anything related to the dark theme */
+    body[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_>`_:

src/pydata_sphinx_theme/__init__.py

@@ -10,6 +10,7 @@
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.errors import ExtensionError
 from sphinx.util import logging
+from pygments.formatters import HtmlFormatter
 
 from .bootstrap_html_translator import BootstrapHTML5Translator
 
@@ -501,6 +502,50 @@ def get_edit_url():
     context["theme_show_toc_level"] = int(context.get("theme_show_toc_level", 1))
 
 
+# -----------------------------------------------------------------------------
+# handle pygment css
+# -----------------------------------------------------------------------------
+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():
+    """
+    Generate the theme-specific pygments.css.
+    There is no way to tell Sphinx how the theme handles modes
+    """
+    light_formatter = HtmlFormatter(style="tango")
+    dark_formatter = HtmlFormatter(style="native")
+
+    lines = []
+
+    light_prefix = 'body[data-theme="light"] .highlight'
+    lines.extend(_get_styles(light_formatter, prefix=light_prefix))
+
+    dark_prefix = 'body[data-theme="dark"] .highlight'
+    lines.extend(_get_styles(dark_formatter, prefix=dark_prefix))
+
+    return "\n".join(lines)
+
+
+# cannot deal with pygments and modes so weoverwrite the pygment css file
+def _overwrite_pygments_css(app, exception=None):
+
+    if exception is not None:
+        return
+
+    assert app.builder
+    with open(os.path.join(app.builder.outdir, "_static", "pygments.css"), "w") as f:
+        f.write(get_pygments_stylesheet())
+
+
 # -----------------------------------------------------------------------------
 
 
@@ -521,6 +566,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(os.fsdecode(theme_path / "_templates"))

src/pydata_sphinx_theme/assets/scripts/index.js

@@ -9,6 +9,10 @@ import "bootstrap";
 
 import "../styles/index.scss";
 
+////////////////////////////////////////////////////////////////////////////////
+// TOC interactivity
+////////////////////////////////////////////////////////////////////////////////
+
 function addTOCInteractivity() {
   // TOC sidebar - add "active" class to parent list
   //
@@ -31,6 +35,10 @@ function addTOCInteractivity() {
   });
 }
 
+////////////////////////////////////////////////////////////////////////////////
+// Scroll
+////////////////////////////////////////////////////////////////////////////////
+
 // Navigation sidebar scrolling to active page
 function scrollToActive() {
   var sidebar = document.querySelector("div.bd-sidebar");
@@ -71,7 +79,74 @@ function scrollToActive() {
   });
 }
 
+////////////////////////////////////////////////////////////////////////////////
+// Theme interaction
+////////////////////////////////////////////////////////////////////////////////
+var prefersDark = window.matchMedia("(prefers-color-scheme: dark)");
+
+function autoTheme(e) {
+  document.body.dataset.theme = prefersDark.matches ? "dark" : "light";
+}
+
+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.body.dataset.mode = mode;
+  document.body.dataset.theme = mode == "auto" ? colorScheme : mode;
+
+  // save mode
+  localStorage.setItem("theme", mode);
+  console.log(`Changed to ${mode} mode.`);
+
+  // add a listener if set on auto
+  prefersDark.onchange = mode == "auto" ? autoTheme : "";
+}
+
+function cycleTheme() {
+  const defaultMode = document.body.dataset.defaultMode || "auto";
+  const currentTheme = localStorage.getItem("theme") || defaultMode;
+
+  if (prefersDark.matches) {
+    // Auto (dark) -> Light -> Dark
+    if (currentTheme === "auto") {
+      setTheme("light");
+    } else if (currentTheme == "light") {
+      setTheme("dark");
+    } else {
+      setTheme("auto");
+    }
+  } else {
+    // Auto (light) -> Dark -> Light
+    if (currentTheme === "auto") {
+      setTheme("dark");
+    } else if (currentTheme == "dark") {
+      setTheme("light");
+    } else {
+      setTheme("auto");
+    }
+  }
+}
+
+function setupTheme() {
+  // setup at least one time
+  const defaultMode = document.body.dataset.defaultMode || "auto";
+  const currentTheme = localStorage.getItem("theme") || defaultMode;
+  setTheme(currentTheme);
+
+  // Attach event handlers for toggling themes
+  const btnList = document.getElementsByClassName("theme-switch");
+  Array.from(btnList).forEach((btn) => {
+    btn.addEventListener("click", cycleTheme);
+  });
+}
+
 // This is equivalent to the .ready() function as described in
 // https://api.jquery.com/ready/
+$(setupTheme);
 $(scrollToActive);
 $(addTOCInteractivity);

src/pydata_sphinx_theme/assets/styles/_admonitions.scss

@@ -9,9 +9,10 @@ div.admonition,
   border-left: 0.2rem solid;
   border-color: rgba(var(--pst-color-admonition-default), 1);
   border-radius: 0.2rem;
-  box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05),
-    0 0 0.0625rem rgba(0, 0, 0, 0.1);
+  box-shadow: 0 0.2rem 0.5rem rgba(var(--pst-color-admonition-shadow), 1),
+    0 0 0.0625rem rgba(var(--pst-color-admonition-shadow), 1);
   transition: color 250ms, background-color 250ms, border-color 250ms;
+  background-color: rgba(var(--pst-color-admonition-background), 1);
 
   // Last item should have no spacing since we'll control that w/ padding
   *:last-child {

src/pydata_sphinx_theme/assets/styles/_api.scss

@@ -13,7 +13,7 @@ table.field-list {
   th.field-name {
     padding: 1px 8px 1px 5px;
     white-space: nowrap;
-    background-color: rgb(238, 238, 238);
+    background-color: rgba(var(--pst-color-background-up), 1);
   }
 
   /* italic font for parameter types */
@@ -87,3 +87,30 @@ table.field-list {
 .sig-name {
   color: rgba(var(--pst-color-inline-code), 1);
 }
+
+// change target color for dark theme
+dt:target {
+  background-color: rgba(var(--pst-color-target), 1);
+}
+
+// adapt ethical add to the theme
+.ethical-sidebar a,
+.ethical-sidebar a:visited,
+.ethical-sidebar a:hover,
+.ethical-sidebar a:active,
+.ethical-footer a,
+.ethical-footer a:visited,
+.ethical-footer a:hover,
+.ethical-footer a:active {
+  color: rgba(var(--pst-color-add-text), 1);
+}
+
+.ethical-sidebar,
+.ethical-footer {
+  background-color: rgba(var(--pst-color-add-background), 1);
+  border: 1px solid rgba(var(--pst-color-add-border), 1);
+  border-radius: 5px;
+  color: rgba(var(--pst-color-add-text), 1);
+  font-size: 14px;
+  line-height: 20px;
+}

src/pydata_sphinx_theme/assets/styles/_base.scss

@@ -6,7 +6,7 @@ html {
 body {
   padding-top: calc(var(--pst-header-height) + 20px);
 
-  background-color: white;
+  background-color: rgba(var(--pst-color-background), 1);
   font-family: var(--pst-font-family-base);
   font-weight: 400;
   line-height: 1.65;
@@ -20,7 +20,7 @@ p {
 
   /* section header in docstring pages */
   &.rubric {
-    border-bottom: 1px solid rgb(201, 201, 201);
+    border-bottom: 1px solid rgba(var(--pst-color-border), 1);
   }
 }
 
@@ -97,7 +97,7 @@ small,
 
 hr {
   border: 0;
-  border-top: 1px solid #e5e5e5;
+  border-top: 1px solid rgba(var(pst-color-border), 1);
 }
 
 pre,
@@ -117,9 +117,9 @@ pre {
   background-color: rgba(var(--pst-color-preformatted-background), 1);
   color: rgba(var(--pst-color-preformatted-text), 1);
   line-height: 1.2em;
-  border: 1px solid rgb(201, 201, 201);
+  border: 1px solid rgba(var(--pst-color-preformatted-border), 1);
   border-radius: 0.2rem;
-  box-shadow: 1px 1px 1px #d8d8d8;
+  box-shadow: 1px 1px 1px rgba(var(--pst-color-preformatted-shadow), 1);
 }
 
 // Override bootstrap by restoring the basic theme default.