Merge pull request #27497 from anntzer/ab

timhoffm · web-flow · commit 6c953e84e159 · 2023-12-12T07:24:23.000+01:00
Clarify that set_axisbelow doesn't move grids below images.
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
