matplotlib
diff --git a/‎lib/matplotlib/patches.py‎
Lines changed: 17 additions & 2 deletions b/‎lib/matplotlib/patches.py‎
Lines changed: 17 additions & 2 deletions
diff --git a/‎tutorials/intermediate/constrainedlayout_guide.py‎
Lines changed: 7 additions & 0 deletions b/‎tutorials/intermediate/constrainedlayout_guide.py‎
Lines changed: 7 additions & 0 deletions
@@ -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
 
@@ -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