Clarify that set_axisbelow doesn't move grids below images.

anntzer · anntzer · commit f1aa13abc347 · 2023-12-11T21:35:21.000+01:00
Even axisbelow(True) sets the grid zorder to 0.5, which is still over
images (zorder 0).  One may want to have grids *below* images if the
image's extent doesn't cover the whole axes limits (e.g. the image only
occupies the top left corner of the Axes and one wants to draw gridlines
on the rest but keep them below the image otherwise).
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -3157,13 +3157,18 @@ def set_axisbelow(self, b):
         b : bool or 'line'
             Possible values:
 
-            - *True* (zorder = 0.5): Ticks and gridlines are below all Artists.
+            - *True* (zorder = 0.5): Ticks and gridlines are below patches and
+              lines, though still above images.
             - 'line' (zorder = 1.5): Ticks and gridlines are above patches
               (e.g. rectangles, with default zorder = 1) but still below lines
               and markers (with their default zorder = 2).
             - *False* (zorder = 2.5): Ticks and gridlines are above patches
               and lines / markers.
 
+        Notes
+        -----
+        For more control, call the `~.Artist.set_zorder` method of each axis.
+
         See Also
         --------
         get_axisbelow
