DOC: add tutorial and example

jklymak · jklymak · commit 101b34ef7e9b · 2018-06-19T10:12:21.000-07:00
diff --git a/doc/users/next_whats_new/subplot_get_gridspec.rst b/doc/users/next_whats_new/subplot_get_gridspec.rst
@@ -2,7 +2,7 @@ Add ``ax.get_gridspec`` to `.SubplotBase`
 -----------------------------------------
 
 New method `.SubplotBase.get_gridspec` is added so that users can
-easily get the gridspec that went into making as axes:
+easily get the gridspec that went into making an axes:
 
   .. code::
 
diff --git a/examples/subplots_axes_and_figures/gridspec_and_subplots.py b/examples/subplots_axes_and_figures/gridspec_and_subplots.py
@@ -0,0 +1,24 @@
+"""
+==================================================
+Combining two subplots using Subplots and gridspec
+==================================================
+
+Sometimes we want to combine two subplots in an axes layout created with
+`.figure.subplots`.  We can get the `.gridspec.Gridspec` from the axes
+and then remove the covered axes and fill the gap with a new bigger axes.
+Here we create a layout with the bottom two axes in the last column combined.
+
+See: :doc:`/tutorials/intermediate/gridspec`
+"""
+import matplotlib.pyplot as plt
+
+fig, axs = plt.subplots(ncols=3, nrows=3)
+gs = axs[1, 2].get_gridspec()
+# remove the underlying axes
+for ax in axs[1:, -1]:
+    ax.remove()
+axbig = fig.add_subplot(gs[1:, -1])
+axbig.annotate('Big Axes \nGridSpec[1:, -1]', (0.1, 0.5),
+               xycoords='axes fraction', va='center')
+
+fig.tight_layout()
diff --git a/tutorials/intermediate/gridspec.py b/tutorials/intermediate/gridspec.py
@@ -122,6 +122,22 @@
 
 fig5.tight_layout()
 
+############################################################################
+# The ``subplots`` and ``gridspec`` methods can be combined since it is
+# sometimes more convenient to make most of the subplots using ``subplots``
+# and then remove some and combine them.  Here we create a layout with
+# the bottom two axes in the last column combined.
+
+fig, axs = plt.subplots(ncols=3, nrows=3)
+gs = axs[1, 2].get_gridspec()
+# remove the underlying axes
+for ax in axs[1:, -1]:
+    ax.remove()
+axbig = fig.add_subplot(gs[1:, -1])
+axbig.annotate('Big Axes \nGridSpec[1:, -1]', (0.1, 0.5),
+               xycoords='axes fraction', va='center')
+
+fig.tight_layout()
 
 ###############################################################################
 # Fine Adjustments to a Gridspec Layout
