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

* 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.

matplotlib#14907

* Made documentation more general for artist limitations in constrained_layout.

* Revised the ConnectionPatch documentation to suggest Figure.add_artist().

Author: Mark Wolf

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

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