🧪 Turn warnings into errors in docs build envs

.readthedocs.yaml

@@ -13,14 +13,19 @@ build:
     python: >-
       3.10
   commands:
-  - python -Im venv "${READTHEDOCS_VIRTUALENV_PATH}"
   - >-
+    PYTHONWARNINGS=error
+    python -Im venv "${READTHEDOCS_VIRTUALENV_PATH}"
+  - >-
+    PYTHONWARNINGS=error
     "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
     pip install tox
   - >-
+    PYTHONWARNINGS=error
     "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
     tox -e build-docs --notest -vvvvv
   - >-
+    PYTHONWARNINGS=error
     SPHINX_BUILDER=dirhtml
     SPHINX_BUILD_OUTPUT_DIRECTORY="${READTHEDOCS_OUTPUT}"/html
     "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im

tox.ini

@@ -355,6 +355,19 @@ passenv =
   SPHINX_BUILDER
   SPHINX_BUILD_OUTPUT_DIRECTORY
   SSH_AUTH_SOCK
+setenv =
+  # 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.
+  # NOTE: Also, one of the warnings comes from the `click-default-group` build:
+  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:setuptools.command.test, \
+    once:pkg_resources is deprecated as an API.:DeprecationWarning:towncrier._settings.load, \
+    once:Deprecated call to `pkg_resources.declare_namespace('sphinxcontrib')`.:DeprecationWarning, \
+    once:setup.py install is deprecated.:
 skip_install = true