Add dark theme and theme switcher (#540)

* docs: exclude files created by jupyter

* set up js for theme change

* demo with only background color change

* set-up all the dark theme colors

* overwrite the pygment css file

* add default_theme parameter

* small update to documentation

* color support for ethical add

* missing alpha channel in css

* docs: fix badly written css comments

* Update src/pydata_sphinx_theme/__init__.py

Co-authored-by: Chris Holdgraf <[email protected]>

* use typescript comment structure

Co-authored-by: Chris Holdgraf <[email protected]>

* make the switch as a btn

* use lighter section headers

* replace all colors with rgba defined colors

* add comments on pygments theme switch

* move ethical-ads to its own scss file

* use theme options to control pygments styling

* change theme switch color

* remind that pygments_style is overwritten

* add comment to js theme management functions

* refactor cycleTheme

* prevent flickering when switching theme

* set the theme-switcher as a template

* document the css trick

Co-authored-by: Chris Holdgraf <[email protected]>

* document the css trick

* change colors to improve accecibility

* change colors to improve accecibility

* apply pre-commit checks

* add the theme switcher to the tests

* quote Furo theme in comments

* add the css trick to all version modified widgets

* include sidebar and topic in the color scheme

* refactor navbar-toggler

* support for version btn

* fix blockquote colors

* listen to the span instead of the a tag

* use the same color for hov and focus

* typo

Co-authored-by: Damian Avila <[email protected]>

* typo

Co-authored-by: Damian Avila <[email protected]>

* set the theme switcher in the navbar-end

* set back the theme-switcher in pydata documentation

* replace orange and green

* use color in the gihub action report

* test the theme switcher

* remove the theme switcher container from the test

* typo

* docs: disclaimer on colors

* docs: typo

* reduce minscore for lighthouse SEO expectations

* Cleaning up the colors for accessibility

* Warning about stability

* Update src/pydata_sphinx_theme/assets/styles/_navbar.scss

Co-authored-by: Damian Avila <[email protected]>

Co-authored-by: Chris Holdgraf <[email protected]>
Co-authored-by: Damian Avila <[email protected]>
Co-authored-by: Chris Holdgraf <[email protected]>

Author: 3 people

.github/workflows/lighthouserc.json

@@ -11,7 +11,7 @@
         "categories:performance": ["error", { "minScore": 0.5 }],
         "categories:accessibility": ["error", { "minScore": 0.8 }],
         "categories:best-practices": ["error", { "minScore": 0.8 }],
-        "categories:seo": ["error", { "minScore": 0.8 }]
+        "categories:seo": ["error", { "minScore": 0.7 }]
       }
     }
   }

.github/workflows/tests.yml

@@ -66,7 +66,7 @@ jobs:
 
       # Run tests under coverage
       - name: Run the tests
-        run: pytest --cov pydata_sphinx_theme --cov-branch --cov-report term-missing:skip-covered --cov-fail-under ${{ env.COVERAGE_THRESHOLD }}
+        run: pytest --color=yes --cov pydata_sphinx_theme --cov-branch --cov-report term-missing:skip-covered --cov-fail-under ${{ env.COVERAGE_THRESHOLD }}
 
       - name: Upload coverage
         if: ${{ always() }}

docs/conf.py

@@ -61,7 +61,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 -------------------------------------------------------
 
@@ -126,7 +126,7 @@
     # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
     # "navbar_start": ["navbar-logo", "navbar-version"],
     # "navbar_center": ["navbar-nav", "navbar-version"],  # Just for testing
-    "navbar_end": ["version-switcher", "navbar-icon-links"],
+    "navbar_end": ["theme-switcher", "version-switcher", "navbar-icon-links"],
     # "left_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"],
     # "footer_items": ["copyright", "sphinx-version", ""]
     "switcher": {

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

@@ -7,6 +7,13 @@ Customizing the theme
 In addition to the configuration options detailed at :ref:`configuration`, it
 is also possible to customize the HTML layout and CSS style of the theme.
 
+.. danger::
+
+    This theme is still under active development, and we make no promises
+    about the stability of any specific HTML structure, CSS variables, etc.
+    Make these customizations at your own risk, and pin versions if you're
+    worried about breaking changes!
+
 .. _custom-css:
 
 Custom CSS Stylesheets
@@ -30,6 +37,41 @@ To add a custom stylesheet, follow these steps:
 
 When you build your documentation, this stylesheet should now be activated.
 
+.. _manage-themes:
+
+Manage 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:
+
+.. 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;
+    }
+
+A complete list of the used colors for this theme can be found in the `pydata default css colors file <pydata-css-colors_>`__.
+
 .. _css-variables:
 
 CSS Theme variables
@@ -58,7 +100,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 different behavior 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_>`_:
@@ -126,6 +169,7 @@ The default body and header fonts can be changed as follows:
     before waiting for the CSS to be parsed, but should be used with care.
 
 .. _pydata-css-variables: https://github.com/pydata/pydata-sphinx-theme/blob/master/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static/styles/theme.css
+.. _pydata-css-colors: https://github.com/pydata/pydata-sphinx-theme/blob/master/src/pydata_sphinx_theme/assets/style/color.scss
 .. _css-variable-help: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
 
 .. meta::

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
 
@@ -547,6 +549,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))
+
+
 # -----------------------------------------------------------------------------
 
 
@@ -567,6 +650,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);