From 394b5539dc337b54f8a730ec126cc7fcb4fdf73c Mon Sep 17 00:00:00 2001
From: Scott Shambaugh <14363975+scottshambaugh@users.noreply.github.com>
Date: Mon, 10 Jun 2024 10:39:28 -0600
Subject: [PATCH] Backport PR #28359: Document that axes unsharing is
 impossible.

---
 lib/matplotlib/axes/_base.py       |  7 ++++---
 lib/matplotlib/figure.py           |  2 ++
 lib/matplotlib/pyplot.py           |  5 +++--
 lib/mpl_toolkits/mplot3d/axes3d.py | 14 ++++++++------
 4 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
index 0164f4e11169..30c4efe80c49 100644
--- a/lib/matplotlib/axes/_base.py
+++ b/lib/matplotlib/axes/_base.py
@@ -597,7 +597,8 @@ def __init__(self, fig,
 
         sharex, sharey : `~matplotlib.axes.Axes`, optional
             The x- or y-`~.matplotlib.axis` is shared with the x- or y-axis in
-            the input `~.axes.Axes`.
+            the input `~.axes.Axes`.  Note that it is not possible to unshare
+            axes.
 
         frameon : bool, default: True
             Whether the Axes frame is visible.
@@ -1221,7 +1222,7 @@ def sharex(self, other):
 
         This is equivalent to passing ``sharex=other`` when constructing the
         Axes, and cannot be used if the x-axis is already being shared with
-        another Axes.
+        another Axes.  Note that it is not possible to unshare axes.
         """
         _api.check_isinstance(_AxesBase, other=other)
         if self._sharex is not None and other is not self._sharex:
@@ -1240,7 +1241,7 @@ def sharey(self, other):
 
         This is equivalent to passing ``sharey=other`` when constructing the
         Axes, and cannot be used if the y-axis is already being shared with
-        another Axes.
+        another Axes.  Note that it is not possible to unshare axes.
         """
         _api.check_isinstance(_AxesBase, other=other)
         if self._sharey is not None and other is not self._sharey:
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
index 0a0ff01a2571..e5f4bb9421cf 100644
--- a/lib/matplotlib/figure.py
+++ b/lib/matplotlib/figure.py
@@ -755,6 +755,8 @@ def subplots(self, nrows=1, ncols=1, *, sharex=False, sharey=False,
             When subplots have a shared axis that has units, calling
             `.Axis.set_units` will update each axis with the new units.
 
+            Note that it is not possible to unshare axes.
+
         squeeze : bool, default: True
             - If True, extra dimensions are squeezed out from the returned
               array of Axes:
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index 1a8298212709..7f8d0bbc6e7f 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -1639,8 +1639,9 @@ def subplots(
         on, use `~matplotlib.axes.Axes.tick_params`.
 
         When subplots have a shared axis that has units, calling
-        `~matplotlib.axis.Axis.set_units` will update each axis with the
-        new units.
+        `.Axis.set_units` will update each axis with the new units.
+
+        Note that it is not possible to unshare axes.
 
     squeeze : bool, default: True
         - If True, extra dimensions are squeezed out from the returned
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
index 18b823ccccb3..91845748880b 100644
--- a/lib/mpl_toolkits/mplot3d/axes3d.py
+++ b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -83,7 +83,8 @@ def __init__(
             axis. A positive angle spins the camera clockwise, causing the
             scene to rotate counter-clockwise.
         sharez : Axes3D, optional
-            Other Axes to share z-limits with.
+            Other Axes to share z-limits with.  Note that it is not possible to
+            unshare axes.
         proj_type : {'persp', 'ortho'}
             The projection type, default 'persp'.
         box_aspect : 3-tuple of floats, default: None
@@ -107,7 +108,8 @@ def __init__(
             The focal length can be computed from a desired Field Of View via
             the equation: focal_length = 1/tan(FOV/2)
         shareview : Axes3D, optional
-            Other Axes to share view angles with.
+            Other Axes to share view angles with.  Note that it is not possible
+            to unshare axes.
 
         **kwargs
             Other optional keyword arguments:
@@ -1307,7 +1309,7 @@ def sharez(self, other):
 
         This is equivalent to passing ``sharez=other`` when constructing the
         Axes, and cannot be used if the z-axis is already being shared with
-        another Axes.
+        another Axes.  Note that it is not possible to unshare axes.
         """
         _api.check_isinstance(Axes3D, other=other)
         if self._sharez is not None and other is not self._sharez:
@@ -1324,9 +1326,9 @@ def shareview(self, other):
         """
         Share the view angles with *other*.
 
-        This is equivalent to passing ``shareview=other`` when
-        constructing the Axes, and cannot be used if the view angles are
-        already being shared with another Axes.
+        This is equivalent to passing ``shareview=other`` when constructing the
+        Axes, and cannot be used if the view angles are already being shared
+        with another Axes.  Note that it is not possible to unshare axes.
         """
         _api.check_isinstance(Axes3D, other=other)
         if self._shareview is not None and other is not self._shareview: