Suppress known warnings from underlying tools

Ref: pypa/pip#12243

Author: webknjaz

tox.ini

@@ -356,7 +356,11 @@ passenv =
   SPHINX_BUILD_OUTPUT_DIRECTORY
   SSH_AUTH_SOCK
 setenv =
-  PYTHONWARNINGS = error
+  # NOTE: `pip` vendors deprecated `setuptools`' `pkg_resources`, causing
+  # NOTE: an unfixable deprecation error, so it's suppressed here. Older
+  # NOTE: `towncrier` versions hit it too. Some `sphinxcontrib` namespace
+  # NOTE: extensions haven't yet been upgraded to using PEP 420 either:
+  PYTHONWARNINGS = error,once:pkg_resources is deprecated as an API.:DeprecationWarning:pip._internal.metadata.importlib._envs,once:pkg_resources is deprecated as an API.:DeprecationWarning:towncrier._settings.load,once:Deprecated call to `pkg_resources.declare_namespace('sphinxcontrib')`.:DeprecationWarning
 skip_install = true