Officially declare pkg_resources as deprecated. Closes #2531.

docs/pkg_resources.rst

@@ -10,6 +10,13 @@ eggs, support for merging packages that have separately-distributed modules or
 subpackages, and APIs for managing Python's current "working set" of active
 packages.
 
+Use of ``pkg_resources`` is discouraged in favor of
+`importlib.resources <https://docs.python.org/3/library/importlib.html#module-importlib.resources>`_,
+`importlib.metadata <https://docs.python.org/3/library/importlib.metadata.html>`_,
+and their backports (`resources <https://pypi.org/project/importlib_resources>`_,
+`metadata <https://pypi.org/project/importlib_metadata>`_).
+Please consider using those libraries instead of pkg_resources.
+
 
 .. contents:: **Table of Contents**