reintegrate modifications from pydata#1264

src/pydata_sphinx_theme/__init__.py

@@ -18,13 +18,14 @@
 
 logger = logging.getLogger(__name__)
 
+
 def update_config(app):
     """Update config with new default values and handle deprecated keys."""
     # By the time `builder-inited` happens, `app.builder.theme_options` already exists.
     # At this point, modifying app.config.html_theme_options will NOT update the
     # page's HTML context (e.g. in jinja, `theme_keyword`).
     # To do this, you must manually modify `app.builder.theme_options`.
-    theme_options = utils.get_theme_options(app)
+    theme_options = utils.get_theme_options_dict(app)
 
     # TODO: deprecation; remove after 0.14 release
     if theme_options.get("logo_text"):
@@ -278,9 +279,9 @@ def _remove_empty_templates(tname):
     # Update version number for the "made with version..." component
     context["theme_version"] = __version__
 
+
 def setup(app: Sphinx) -> Dict[str, str]:
     """Setup the Sphinx application."""
-
     here = Path(__file__).parent.resolve()
     theme_path = here / "theme" / "pydata_sphinx_theme"
 

src/pydata_sphinx_theme/logo.py

@@ -11,7 +11,7 @@
 from sphinx.util import isurl, logging
 from sphinx.util.fileutil import copy_asset_file
 
-from .utils import get_theme_options
+from .utils import get_theme_options_dict
 
 logger = logging.getLogger(__name__)
 
@@ -60,8 +60,7 @@ def copy_logo_images(app: Sphinx, exception=None) -> None:
 
     If logo image paths are given, copy them to the `_static` folder Then we can link to them directly in an html_page_context event.
     """
-    theme_options = get_theme_options(app)
-    logo = theme_options.get("logo", {})
+    logo = get_theme_options_dict(app).get("logo", {})
     staticdir = Path(app.builder.outdir) / "_static"
     for kind in ["light", "dark"]:
         path_image = logo.get(f"image_{kind}")

src/pydata_sphinx_theme/pygment.py

@@ -10,7 +10,7 @@
 from sphinx.application import Sphinx
 from sphinx.util import logging
 
-from .utils import get_theme_options
+from .utils import get_theme_options_dict
 
 logger = logging.getLogger(__name__)
 
@@ -74,26 +74,30 @@ def overwrite_pygments_css(app: Sphinx, exception=None):
         if fallback not in pygments_styles:
             fallback = pygments_styles[0]  # should resolve to "default"
 
-        # see if user specified a light/dark pygments theme, if not, use the
-        # one we set in theme.conf
+        # see if user specified a light/dark pygments theme:
         style_key = f"pygment_{light_or_dark}_style"
 
-        # globalcontext sometimes doesn't exist so this ensures we do not error
-        theme_name = get_theme_options(app).get(style_key, None)
-        if theme_name is None and hasattr(app.builder, "globalcontext"):
-            theme_name = app.builder.globalcontext.get(f"theme_{style_key}")
+        style_name = get_theme_options_dict(app).get(style_key, None)
+        # if not, use the one we set in `theme.conf`:
+        if style_name is None and hasattr(app.builder, "theme"):
+            style_name = app.builder.theme.get_options()[style_key]
 
         # make sure we can load the style
-        if theme_name not in pygments_styles:
-            logger.warning(
-                f"Color theme {theme_name} not found by pygments, falling back to {fallback}."
-            )
-            theme_name = fallback
+        if style_name not in pygments_styles:
+            # only warn if user asked for a highlight theme that we can't find
+            if style_name is not None:
+                logger.warning(
+                    f"Highlighting style {style_name} not found by pygments, "
+                    f"falling back to {fallback}."
+                )
+            style_name = fallback
+
         # assign to the appropriate variable
         if light_or_dark == "light":
-            light_theme = theme_name
+            light_theme = style_name
         else:
-            dark_theme = theme_name
+            dark_theme = style_name
+
     # re-write pygments.css
     pygment_css = Path(app.builder.outdir) / "_static" / "pygments.css"
     with pygment_css.open("w") as f:

src/pydata_sphinx_theme/utils.py

@@ -6,19 +6,20 @@
 from sphinx.application import Sphinx
 
 
-def get_theme_options(app: Sphinx) -> Dict[str, Any]:
+def get_theme_options_dict(app: Sphinx) -> Dict[str, Any]:
     """Return theme options for the application w/ a fallback if they don't exist.
 
-    In general we want to modify app.builder.theme_options if it exists, so prefer that first.
+    The "top-level" mapping (the one we should usually check first, and modify
+    if desired) is ``app.builder.theme_options``. It is created by Sphinx as a
+    copy of ``app.config.html_theme_options`` (containing user-configs from
+    their ``conf.py``); sometimes that copy never occurs though which is why we
+    check both.
     """
     if hasattr(app.builder, "theme_options"):
-        # In most HTML build cases this will exist except for some circumstances (see below).
         return app.builder.theme_options
     elif hasattr(app.config, "html_theme_options"):
-        # For example, linkcheck will have this configured but won't be in builder obj.
         return app.config.html_theme_options
     else:
-        # Empty dictionary as a fail-safe.
         return {}