bpo-134740: Add missing documentation for importlib.metadata.distributions()

Add documentation for the distributions() function, Distribution.discover() method,
and DistributionFinder classes that were missing from the importlib.metadata
documentation despite being part of the public API.

Author: ashm-dev

Doc/library/importlib.metadata.rst

@@ -410,6 +410,20 @@ Distributions
    Raises :exc:`PackageNotFoundError` if the named distribution
    package is not installed in the current Python environment.
 
+.. function:: distributions(**kwargs)
+
+   Get all :class:`Distribution` instances in the current environment.
+
+   Any keyword arguments are passed to the ``find_distributions()`` method
+   of the registered distribution finders (see :class:`DistributionFinder`).
+
+   Common keyword arguments include:
+
+   * ``name``: Filter to distributions matching this package name
+   * ``path``: Search these path segments (defaults to :data:`sys.path`)
+
+   :return: An iterable of :class:`Distribution` instances.
+
 .. class:: Distribution
 
    Details of an installed distribution package.
@@ -418,6 +432,47 @@ Distributions
    equal, even if they relate to the same installed distribution and
    accordingly have the same attributes.
 
+   .. classmethod:: discover(*, context=None, **kwargs)
+
+      Return an iterable of Distribution objects for all packages.
+
+      Pass a ``context`` or pass keyword arguments for constructing
+      a context.
+
+      :param context: A :class:`DistributionFinder.Context` object.
+      :param kwargs: Context parameters used to construct a new context if one
+                    is not supplied.
+      :return: Iterable of Distribution objects for packages matching
+               the context.
+
+.. class:: DistributionFinder
+
+   An abstract base class subclass of :class:`importlib.abc.MetaPathFinder`
+   capable of discovering installed distributions.
+
+   Custom providers should implement this interface to supply metadata
+   for distributions that cannot be discovered through the file system
+   or other built-in mechanisms.
+
+   See the section on :ref:`implementing-custom-providers` for more details.
+
+.. class:: DistributionFinder.Context
+
+   Context object used to provide parameters when discovering distributions.
+
+   Keyword arguments supplied to :func:`distributions` or
+   :meth:`Distribution.discover` are stored as attributes in the context
+   object and can be used by distribution finders to filter or customize
+   their search results.
+
+   The context provides these attributes:
+
+   * ``name``: A package name to match, or ``None`` to match all distributions
+   * ``path``: A list of directories to search (defaults to :data:`sys.path`)
+
+   Custom distribution finders can accept other keyword parameters through
+   this context.
+
 While the module level API described above is the most common and convenient usage,
 you can get all of that information from the :class:`!Distribution` class.
 :class:`!Distribution` is an abstract object that represents the metadata for
@@ -467,6 +522,8 @@ This metadata finder search defaults to ``sys.path``, but varies slightly in how
 - ``importlib.metadata`` will incidentally honor :py:class:`pathlib.Path` objects on ``sys.path`` even though such values will be ignored for imports.
 
 
+.. _implementing-custom-providers:
+
 Implementing Custom Providers
 =============================