Documentation for using ConnectionPatch across Axes with constrained_… (#14957)

Mark Wolf · ImportanceOfBeingErnest · commit b34c60523ea4 · 2019-08-15T00:37:45.000+02:00
* Documentation for using ConnectionPatch across Axes with constrained_layout. When using a figure with contrained layout management, adding a ConnectionPatch between different subplot Axes breaks the layout. The artist should be removed from layout considerations before being added to the axes. This commit notes this fix in the documentation. #14907 * Made documentation more general for artist limitations in constrained_layout. * Revised the ConnectionPatch documentation to suggest Figure.add_artist().
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -4215,8 +4215,7 @@ def __init__(self, xyA, xyB, coordsA, coordsB=None,
                  clip_on=False,
                  dpi_cor=1.,
                  **kwargs):
-        """
-        Connect point *xyA* in *coordsA* with point *xyB* in *coordsB*
+        """Connect point *xyA* in *coordsA* with point *xyB* in *coordsB*
 
         Valid keys are
 
@@ -4259,6 +4258,22 @@ def __init__(self, xyA, xyB, coordsA, coordsB=None,
 
         Alternatively they can be set to any valid
         `~matplotlib.transforms.Transform`.
+
+        .. note::
+
+           Using :class:`~matplotlib.patches.ConnectionPatch` across
+           two :class:`~matplotlib.axes.Axes` instances is not
+           directly compatible with :doc:`constrained layout
+           </tutorials/intermediate/constrainedlayout_guide>`. Add the
+           artist directly to the :class:`~matplotlib.figure.Figure`
+           instead of adding it to a specific Axes.
+
+           .. code-block:: default
+
+              fig, ax = plt.subplots(1, 2, constrained_layout=True)
+              con = ConnectionPatch(..., axesA=ax[0], axesB=ax[1])
+              fig.add_artist(con)
+
         """
         if coordsB is None:
             coordsB = coordsA
diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py
@@ -581,6 +581,13 @@ def docomplicated(suptitle=None):
 #
 # * There are small differences in how the backends handle rendering fonts,
 #   so the results will not be pixel-identical.
+#
+# * An artist using axes coordinates that extend beyond the axes
+#   boundary will result in unusual layouts when added to an
+#   axes. This can be avoided by adding the artist directly to the
+#   :class:`~matplotlib.figure.Figure` using
+#   :meth:`~matplotlib.figure.Figure.add_artist`. See
+#   :class:`~matplotlib.patches.ConnectionPatch` for an example.
 
 ###########################################################
 # Debugging
