matplotlib · NelleV · Jul 13, 2018 · Jul 10, 2018 · Jul 11, 2018
diff --git a/.flake8 b/.flake8
@@ -251,6 +251,7 @@ per-file-ignores =
     examples/style_sheets/plot_solarizedlight2.py: E501
     examples/subplots_axes_and_figures/axes_margins.py: E402
     examples/subplots_axes_and_figures/axes_zoom_effect.py: E402
+    examples/subplots_axes_and_figures/demo_constrained_layout.py: E402
     examples/subplots_axes_and_figures/demo_tight_layout.py: E402
     examples/subplots_axes_and_figures/two_scales.py: E402
     examples/tests/backend_driver_sgskip.py: E402, E501

diff --git a/examples/subplots_axes_and_figures/demo_constrained_layout.py b/examples/subplots_axes_and_figures/demo_constrained_layout.py
@@ -0,0 +1,76 @@
+"""
+=====================================
+Resizing axes with constrained layout
+=====================================
+
+Constrained layout attempts to resize subplots in
+a figure so that there are no overlaps between axes objects and labels
+on the axes.
+
+See :doc:`/tutorials/intermediate/constrainedlayout_guide` for more details and
+:doc:`/tutorials/intermediate/tight_layout_guide` for an alternative.
+
+"""
+
+import matplotlib.pyplot as plt
+import itertools
+import warnings
+
+
+def example_plot(ax):
+    ax.plot([1, 2])
+    ax.set_xlabel('x-label', fontsize=12)
+    ax.set_ylabel('y-label', fontsize=12)
+    ax.set_title('Title', fontsize=14)
+
+
+###############################################################################
+# If we don't use constrained_layout, then labels overlap the axes
+
+fig, axs = plt.subplots(nrows=2, ncols=2, constrained_layout=False)
+
+for ax in axs.flatten():
+    example_plot(ax)
+
+###############################################################################
+# adding ``constrained_layout=True`` automatically adjusts.
+
+fig, axs = plt.subplots(nrows=2, ncols=2, constrained_layout=True)
+
+for ax in axs.flatten():
+    example_plot(ax)
+
+###############################################################################
+# Below is a more complicated example using nested gridspecs.
+
+fig = plt.figure(constrained_layout=True)
+
+import matplotlib.gridspec as gridspec
+
+gs0 = gridspec.GridSpec(1, 2, figure=fig)
+
+gs1 = gridspec.GridSpecFromSubplotSpec(3, 1, subplot_spec=gs0[0])
+for n in range(3):
+    ax = fig.add_subplot(gs1[n])
+    example_plot(ax)
+
+
+gs2 = gridspec.GridSpecFromSubplotSpec(2, 1, subplot_spec=gs0[1])
+for n in range(2):
+    ax = fig.add_subplot(gs2[n])
+    example_plot(ax)
+
+plt.show()
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions and methods is shown in this example:
+
+import matplotlib
+matplotlib.gridspec.GridSpec
+matplotlib.gridspec.GridSpecFromSubplotSpec
diff --git a/examples/subplots_axes_and_figures/demo_tight_layout.py b/examples/subplots_axes_and_figures/demo_tight_layout.py
@@ -1,7 +1,14 @@
 """
-=================
-Demo Tight Layout
-=================
+===============================
+Resizing axes with tight layout
+===============================
+
+`~.figure.Figure.tight_layout` attempts to resize subplots in
+a figure so that there are no overlaps between axes objects and labels
+on the axes.
+
+See :doc:`/tutorials/intermediate/tight_layout_guide` for more details and
+:doc:`/tutorials/intermediate/constrainedlayout_guide` for an alternative.
 
 """
 
@@ -133,3 +140,19 @@ def example_plot(ax):
 gs2.update(top=top, bottom=bottom)
 
 plt.show()
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions and methods is shown in this example:
+
+import matplotlib
+matplotlib.pyplot.tight_layout
+matplotlib.figure.Figure.tight_layout
+matplotlib.figure.Figure.add_subplot
+matplotlib.pyplot.subplot2grid
+matplotlib.gridspec.GridSpec
diff --git a/examples/subplots_axes_and_figures/gridspec_multicolumn.py b/examples/subplots_axes_and_figures/gridspec_multicolumn.py
@@ -0,0 +1,33 @@
+"""
+=======================================================
+Using Gridspec to make multi-column/row subplot layouts
+=======================================================
+
+`.GridSpec` is a flexible way to layout
+subplot grids.  Here is an example with a 3x3 grid, and
+axes spanning all three columns, two columns, and two rows.
+
+"""
+import matplotlib.pyplot as plt
+from matplotlib.gridspec import GridSpec
+
+
+def format_axes(fig):
+    for i, ax in enumerate(fig.axes):
+        ax.text(0.5, 0.5, "ax%d" % (i+1), va="center", ha="center")
+        ax.tick_params(labelbottom=False, labelleft=False)
+
+fig = plt.figure(constrained_layout=True)
+
+gs = GridSpec(3, 3, figure=fig)
+ax1 = fig.add_subplot(gs[0, :])
+# identical to ax1 = plt.subplot(gs.new_subplotspec((0, 0), colspan=3))
+ax2 = fig.add_subplot(gs[1, :-1])
+ax3 = fig.add_subplot(gs[1:, -1])
+ax4 = fig.add_subplot(gs[-1, 0])
+ax5 = fig.add_subplot(gs[-1, -2])
+
+fig.suptitle("GridSpec")
+format_axes(fig)
+
+plt.show()
diff --git a/examples/userdemo/demo_gridspec04.py → ...plots_axes_and_figures/gridspec_nested.py b/examples/userdemo/demo_gridspec04.py → ...plots_axes_and_figures/gridspec_nested.py
@@ -1,24 +1,26 @@
 """
-===============
-Demo Gridspec04
-===============
+================
+Nested Gridspecs
+================
+
+GridSpecs can be nested, so that a subplot from a parent GridSpec can
+set the position for a nested grid of subplots.
 
 """
 import matplotlib.pyplot as plt
 import matplotlib.gridspec as gridspec
 
 
-def make_ticklabels_invisible(fig):
+def format_axes(fig):
     for i, ax in enumerate(fig.axes):
         ax.text(0.5, 0.5, "ax%d" % (i+1), va="center", ha="center")
         ax.tick_params(labelbottom=False, labelleft=False)
 
 
 # gridspec inside gridspec
-
 f = plt.figure()
 
-gs0 = gridspec.GridSpec(1, 2)
+gs0 = gridspec.GridSpec(1, 2, figure=f)
 
 gs00 = gridspec.GridSpecFromSubplotSpec(3, 3, subplot_spec=gs0[0])
 
@@ -40,6 +42,6 @@ def make_ticklabels_invisible(fig):
 f.add_subplot(ax6)
 
 plt.suptitle("GridSpec Inside GridSpec")
-make_ticklabels_invisible(f)
+format_axes(f)
 
 plt.show()
diff --git a/examples/userdemo/demo_gridspec02.py b/examples/userdemo/demo_gridspec02.py