DOC: Update tutorial to explain colorbar API

jklymak · jklymak · commit e729962972f9 · 2018-02-28T10:49:30.000-08:00
diff --git a/lib/matplotlib/axes/_subplots.py b/lib/matplotlib/axes/_subplots.py
@@ -173,7 +173,9 @@ def _make_twin_axes(self, *kl, **kwargs):
         """
         from matplotlib.projections import process_projection_requirements
         if 'sharex' in kwargs and 'sharey' in kwargs:
-            raise ValueError("Twinned Axes may share only one axis.")
+            if (not (kwargs['sharex'] == self ) and
+                        not (kwargs['sharex'] == self)):
+                raise ValueError("Twinned Axes may share only one axis.")
         kl = (self.get_subplotspec(),) + kl
         projection_class, kwargs, key = process_projection_requirements(
             self.figure, *kl, **kwargs)
diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py
@@ -105,7 +105,7 @@ def example_plot(ax, fontsize=12, nodec=False):
 fig.colorbar(im, ax=ax, shrink=0.6)
 
 ############################################################################
-# If you specify multiple axes to the ``ax`` argument of ``colorbar``,
+# If you specify a list of axes to the ``ax`` argument of ``colorbar``,
 # constrained_layout will take space from all axes that share the same
 # gridspec.
 
@@ -114,6 +114,31 @@ def example_plot(ax, fontsize=12, nodec=False):
     im = ax.pcolormesh(arr, rasterized=True)
 fig.colorbar(im, ax=axs, shrink=0.6)
 
+############################################################################
+# Note that there is a bit of a subtlety when specifying a single axes
+# as the parent.  In the following, it might be desirable and expected
+# for the colorbars to line up, but they don't because the colorbar paired
+# with the bottom axes is tied to the subplotspec of the axes, and hence
+# shrinks when the gridspec-level colorbar is added.
+
+fig, axs = plt.subplots(3, 1, figsize=(4, 4), constrained_layout=True)
+for ax in axs[:2]:
+    im = ax.pcolormesh(arr, rasterized=True)
+fig.colorbar(im, ax=axs[:2], shrink=0.6)
+im = axs[2].pcolormesh(arr, rasterized=True)
+fig.colorbar(im, ax=axs[2], shrink=0.6)
+
+############################################################################
+# The API to make a single-axes behave like a list of axes is to specify
+# it as a list, as below:
+
+fig, axs = plt.subplots(3, 1, figsize=(4, 4), constrained_layout=True)
+for ax in axs[:2]:
+    im = ax.pcolormesh(arr, rasterized=True)
+fig.colorbar(im, ax=axs[:2], shrink=0.6)
+im = axs[2].pcolormesh(arr, rasterized=True)
+fig.colorbar(im, ax=[axs[2]], shrink=0.6)
+
 ####################################################
 # Suptitle
 # =========
