Merge pull request #19917 from meeseeksmachine/auto-backport-of-pr-19911-on-v3.4.x

QuLogic · web-flow · commit ea96b244812c · 2021-04-08T21:44:49.000-04:00
Backport PR #19911 on branch v3.4.x (Shorten "how-to draw order")
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -261,25 +261,12 @@ setting in the right subplots.
 
 .. _howto-set-zorder:
 
-Control the depth of plot elements
-----------------------------------
-
-Within an axes, the order that the various lines, markers, text,
-collections, etc appear is determined by the
-:meth:`~matplotlib.artist.Artist.set_zorder` property.  The default
-order is patches, lines, text, with collections of lines and
-collections of patches appearing at the same level as regular lines
-and patches, respectively::
-
-    line, = ax.plot(x, y, zorder=10)
-
-.. only:: html
-
-    See :doc:`/gallery/misc/zorder_demo` for a complete example.
+Control the draw order of plot elements
+---------------------------------------
 
-You can also use the Axes property
-:meth:`~matplotlib.axes.Axes.set_axisbelow` to control whether the grid
-lines are placed above or below your other plot elements.
+The draw order of plot elements, and thus which elements will be on top, is
+determined by the `~.Artist.set_zorder` property.
+See :doc:`/gallery/misc/zorder_demo` for a detailed description.
 
 .. _howto-axis-equal:
 
diff --git a/examples/misc/zorder_demo.py b/examples/misc/zorder_demo.py
@@ -24,8 +24,12 @@
 
 .. note::
 
-   `~.axes.Axes.set_axisbelow` and :rc:`axes.axisbelow` can further modify the
-   zorder of ticks and grid lines.
+   `~.axes.Axes.set_axisbelow` and :rc:`axes.axisbelow` are convenient helpers
+   for setting the zorder of ticks and grid lines.
+
+Drawing is done per `~.axes.Axes` at a time. If you have overlapping Axes, all
+elements of the second Axes are drawn on top of the first Axes, irrespective of
+their relative zorder.
 """
 
 import matplotlib.pyplot as plt
