Silence warnings (#1542)

* avoid webpack warning during asset compile

* avoid frozen modules warning during import

* try to make jupyterlite quieter

* add config option to silence warnings

* fix tests

* add docs

* hide conditional warning logic in utils

Author: drammock

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", "")
 

docs/conf.py

@@ -48,6 +48,8 @@
     "_extension.gallery_directive",
 ]
 
+jupyterlite_config = "jupyterlite_config.json"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/jupyterlite_config.json

@@ -0,0 +1,7 @@
+{
+  "LiteBuildConfig": {
+    "Application": {
+      "log_level": 40
+    }
+  }
+}

docs/user_guide/index.md

@@ -74,5 +74,6 @@ accessibility
 analytics
 static_assets
 performance
+warnings
 readthedocs
 ```

docs/user_guide/warnings.rst

@@ -0,0 +1,15 @@
+
+Theme changes, deprecations, and warnings
+=========================================
+
+Generally speaking, the best source of information about changes to the theme will be the release changelog.
+We try to avoid raising warnings within theme code, which means sometimes the theme will change (perhaps significantly) without deprecation warnings or other alerts.
+Still, we occasionally do warn about things like (upcoming) changes to the theme's default config values.
+If you prefer *not* to receive such warnings, there is a config value to suppress them:
+
+.. code-block::
+    :caption: conf.py
+
+    html_theme_options = {
+        "surface_warnings": False
+    }

noxfile.py

@@ -77,6 +77,8 @@ def docs(session: nox.Session) -> None:
         "-v",
         "-w",
         "warnings.txt",
+        # suppress Py3.11's new "can't debug frozen modules" warning
+        env=dict(PYDEVD_DISABLE_FILE_VALIDATION="1"),
     )
     session.run("python", "tests/utils/check_warnings.py")
 
@@ -92,7 +94,13 @@ def docs_live(session: nox.Session) -> None:
             "sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b"
         )
     session.run(
-        "stb", "serve", "docs", "--open-browser", "--re-ignore=locale|api|_build"
+        "stb",
+        "serve",
+        "docs",
+        "--open-browser",
+        r"--re-ignore=locale|api|_build|\.jupyterlite\.doit\.db",
+        # suppress Py3.11's new "can't debug frozen modules" warning
+        env=dict(PYDEVD_DISABLE_FILE_VALIDATION="1"),
     )