Document that axes unsharing is impossible.

anntzer · anntzer · commit fbdf7f3c843d · 2024-06-07T18:48:58.000+02:00
The feature may perhaps be desirable, but let's document the current
state of things.
diff --git 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
@@ -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
@@ -1651,8 +1651,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
