Merge pull request matplotlib#19924 from anntzer/imreadd

DOC: Discourage use of imread & improve its docs.

Author: tacaswell

lib/matplotlib/image.py

@@ -1425,6 +1425,11 @@ def imread(fname, format=None):
     """
     Read an image from a file into an array.
 
+    .. note::
+
+        This function exists for historical reasons.  It is recommended to
+        use `PIL.Image.open` instead for loading images.
+
     Parameters
     ----------
     fname : str or file-like
@@ -1435,9 +1440,11 @@ def imread(fname, format=None):
         for reading and pass the result to Pillow, e.g. with
         ``PIL.Image.open(urllib.request.urlopen(url))``.
     format : str, optional
-        The image file format assumed for reading the data. If not
-        given, the format is deduced from the filename.  If nothing can
-        be deduced, PNG is tried.
+        The image file format assumed for reading the data.  The image is
+        loaded as a PNG file if *format* is set to "png", if *fname* is a path
+        or opened file with a ".png" extension, or if it is an URL.  In all
+        other cases, *format* is ignored and the format is auto-detected by
+        `PIL.Image.open`.
 
     Returns
     -------
@@ -1447,6 +1454,10 @@ def imread(fname, format=None):
         - (M, N) for grayscale images.
         - (M, N, 3) for RGB images.
         - (M, N, 4) for RGBA images.
+
+        PNG images are returned as float arrays (0-1).  All other formats are
+        returned as int arrays, with a bit depth determined by the file's
+        contents.
     """
     # hide imports to speed initial import on systems with slow linkers
     from urllib import parse