add config option to silence warnings

docs/_extension/gallery_directive.py

@@ -75,7 +75,7 @@ def run(self) -> List[nodes.Node]:
             path_doc = Path(path_doc).parent
             path_data = (path_doc / path_data_rel).resolve()
             if not path_data.exists():
-                logger.warn(f"Could not find grid data at {path_data}.")
+                logger.info(f"Could not find grid data at {path_data}.")
                 nodes.text("No grid data found at {path_data}.")
                 return
             yaml_string = path_data.read_text()
@@ -86,7 +86,6 @@ def run(self) -> List[nodes.Node]:
         # and generate a card item for each of them
         grid_items = []
         for item in safe_load(yaml_string):
-
             # remove parameters that are not needed for the card options
             title = item.pop("title", "")
 

src/pydata_sphinx_theme/__init__.py

@@ -26,40 +26,47 @@ def update_config(app):
     # 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_dict(app)
+    should_warn = theme_options.get("surface_warnings", False)
 
     # TODO: deprecation; remove after 0.14 release
     if theme_options.get("logo_text"):
         logo = theme_options.get("logo", {})
         logo["text"] = theme_options.get("logo_text")
         theme_options["logo"] = logo
-        logger.warning(
-            "The configuration `logo_text` is deprecated." "Use `'logo': {'text': }`."
-        )
+        if should_warn:
+            logger.warning(
+                "The configuration `logo_text` is deprecated. "
+                "Use `'logo': {'text': }`."
+            )
 
     # TODO: DEPRECATE after 0.14
     if theme_options.get("footer_items"):
         theme_options["footer_start"] = theme_options.get("footer_items")
-        logger.warning(
-            "`footer_items` is deprecated. Use `footer_start` or `footer_end` instead."
-        )
+        if should_warn:
+            logger.warning(
+                "`footer_items` is deprecated. "
+                "Use `footer_start` or `footer_end` instead."
+            )
 
     # TODO: DEPRECATE after v0.15
     if theme_options.get("favicons"):
-        logger.warning(
-            "The configuration `favicons` is deprecated."
-            "Use the sphinx-favicon extension instead."
-        )
+        if should_warn:
+            logger.warning(
+                "The configuration `favicons` is deprecated. "
+                "Use the sphinx-favicon extension instead."
+            )
 
     # TODO: in 0.15, set the default navigation_with_keys value to False and remove this deprecation notice
     if theme_options.get("navigation_with_keys", None) is None:
-        logger.warning(
-            "The default value for `navigation_with_keys` will change to `False` in "
-            "the next release. If you wish to preserve the old behavior for your site, "
-            "set `navigation_with_keys=True` in the `html_theme_options` dict in your "
-            "`conf.py` file."
-            "Be aware that `navigation_with_keys = True` has negative accessibility implications:"
-            "https://github.com/pydata/pydata-sphinx-theme/issues/1492"
-        )
+        if should_warn:
+            logger.warning(
+                "The default value for `navigation_with_keys` will change to `False` "
+                "in the next release. If you wish to preserve the old behavior for "
+                "your site, set `navigation_with_keys=True` in the "
+                "`html_theme_options` dict in your `conf.py` file. Be aware that "
+                "`navigation_with_keys = True` has negative accessibility implications:"
+                " https://github.com/pydata/pydata-sphinx-theme/issues/1492"
+            )
         theme_options["navigation_with_keys"] = False
 
     # Validate icon links
@@ -101,20 +108,21 @@ def update_config(app):
                 reading_error = repr(e)
 
         if reading_error is not None:
-            logger.warning(
-                f'The version switcher "{json_url}" file cannot be read due to the following error:\n'
-                f"{reading_error}"
-            )
+            if should_warn:
+                logger.warning(
+                    f'The version switcher "{json_url}" file cannot be read due to '
+                    f"the following error:\n{reading_error}"
+                )
         else:
             # check that the json file is not illformed,
             # throw a warning if the file is ill formed and an error if it's not json
             switcher_content = json.loads(content)
             missing_url = any(["url" not in e for e in switcher_content])
             missing_version = any(["version" not in e for e in switcher_content])
-            if missing_url or missing_version:
+            if should_warn and missing_url or missing_version:
                 logger.warning(
-                    f'The version switcher "{json_url}" file is malformed'
-                    ' at least one of the items is missing the "url" or "version" key'
+                    f'The version switcher "{json_url}" file is malformed; '
+                    'at least one of the items is missing the "url" or "version" key'
                 )
 
     # Add an analytics ID to the site if provided

src/pydata_sphinx_theme/logo.py

@@ -60,6 +60,8 @@ 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_dict(app)
+    should_warn = theme_options.get("surface_warnings", False)
     logo = get_theme_options_dict(app).get("logo", {})
     staticdir = Path(app.builder.outdir) / "_static"
     for kind in ["light", "dark"]:
@@ -70,7 +72,7 @@ def copy_logo_images(app: Sphinx, exception=None) -> None:
             # file already exists in static dir e.g. because a theme has
             # bundled the logo and installed it there
             continue
-        if not (Path(app.srcdir) / path_image).exists():
+        if should_warn and not (Path(app.srcdir) / path_image).exists():
             logger.warning(f"Path to {kind} image logo does not exist: {path_image}")
         # Ensure templates cannot be passed for logo path to avoid security vulnerability
         if path_image.lower().endswith("_t"):

src/pydata_sphinx_theme/pygment.py

@@ -61,6 +61,9 @@ def overwrite_pygments_css(app: Sphinx, exception=None):
     Fallbacks are defined in this function in case the user-requested (or our
     theme-specified) pygments theme is not available.
     """
+    theme_options = get_theme_options_dict(app)
+    should_warn = theme_options.get("surface_warnings", False)
+
     if exception is not None:
         return
 
@@ -76,15 +79,15 @@ def overwrite_pygments_css(app: Sphinx, exception=None):
 
         # see if user specified a light/dark pygments theme:
         style_key = f"pygment_{light_or_dark}_style"
-        style_name = get_theme_options_dict(app).get(style_key, None)
+        style_name = theme_options.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 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:
+            if style_name is not None and should_warn:
                 logger.warning(
                     f"Highlighting style {style_name} not found by pygments, "
                     f"falling back to {fallback}."

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -36,6 +36,7 @@ check_switcher = True
 pygment_light_style = a11y-high-contrast-light
 pygment_dark_style = a11y-high-contrast-dark
 logo =
+surface_warnings = True
 
 # Template placement in theme layouts
 navbar_start = navbar-logo