don't warn on fallback if no highlight theme was requested (#1264)

* don't warn on fallback if no highlight theme requested

* fix it for good

* move event back to build-finished

* better name, better doc

* cleanup

* simplify/safer

src/pydata_sphinx_theme/__init__.py

@@ -32,19 +32,20 @@
 logger = logging.getLogger(__name__)
 
 
-def _get_theme_options(app):
-    """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.
+def _get_theme_options_dict(app):
+    """Get the Sphinx theme options dictionary (or fallback to an empty dict).
+
+    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 {}
 
 
@@ -59,7 +60,7 @@ def update_config(app):
     # 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 = _get_theme_options(app)
+    theme_options = _get_theme_options_dict(app)
 
     # TODO: deprecation; remove after 0.14 release
     if theme_options.get("logo_text"):
@@ -948,26 +949,26 @@ def _overwrite_pygments_css(app, 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:
@@ -1170,8 +1171,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}")