Merge pull request matplotlib#20528 from anntzer/sd

Merge subplot_demo into subplot example.

Author: timhoffm

doc/users/prev_whats_new/whats_new_1.0.rst

@@ -44,7 +44,7 @@ indexing (starts with 0).  e.g.::
   fig, axarr = plt.subplots(2, 2)
   axarr[0,0].plot([1,2,3])   # upper, left
 
-See :doc:`/gallery/subplots_axes_and_figures/subplot_demo` for several code examples.
+See :doc:`/gallery/subplots_axes_and_figures/subplot` for several code examples.
 
 Contour fixes and and triplot
 -----------------------------

examples/subplots_axes_and_figures/subplot.py

@@ -4,18 +4,25 @@
 =================
 
 Simple demo with multiple subplots.
+
+For more options, see :doc:`/gallery/subplots_axes_and_figures/subplots_demo`.
+
+.. redirect-from:: /gallery/subplots_axes_and_figures/subplot_demo
 """
+
 import numpy as np
 import matplotlib.pyplot as plt
 
-###############################################################################
-
+# Create some fake data.
 x1 = np.linspace(0.0, 5.0)
-x2 = np.linspace(0.0, 2.0)
-
 y1 = np.cos(2 * np.pi * x1) * np.exp(-x1)
+x2 = np.linspace(0.0, 2.0)
 y2 = np.cos(2 * np.pi * x2)
 
+###############################################################################
+# `~.pyplot.subplots()` is the recommended method to generate simple subplot
+# arrangements:
+
 fig, (ax1, ax2) = plt.subplots(2, 1)
 fig.suptitle('A tale of 2 subplots')
 
@@ -28,22 +35,8 @@
 
 plt.show()
 
-#############################################################################
-#
-#
-# Alternative Method For Creating Multiple Plots
-# """"""""""""""""""""""""""""""""""""""""""""""
-#
-# Subplots can also be generated using `~.pyplot.subplot()` \
-# as in the following example:
-#
-
-
-x1 = np.linspace(0.0, 5.0)
-x2 = np.linspace(0.0, 2.0)
-
-y1 = np.cos(2 * np.pi * x1) * np.exp(-x1)
-y2 = np.cos(2 * np.pi * x2)
+###############################################################################
+# Subplots can also be generated one at a time using `~.pyplot.subplot()`:
 
 plt.subplot(2, 1, 1)
 plt.plot(x1, y1, 'o-')

examples/subplots_axes_and_figures/subplot_demo.py

@@ -273,10 +273,9 @@ def f(t):
 # which allows you to specify the location as ``axes([left, bottom,
 # width, height])`` where all values are in fractional (0 to 1)
 # coordinates.  See :doc:`/gallery/subplots_axes_and_figures/axes_demo` for an example of
-# placing axes manually and :doc:`/gallery/subplots_axes_and_figures/subplot_demo` for an
+# placing axes manually and :doc:`/gallery/subplots_axes_and_figures/subplot` for an
 # example with lots of subplots.
 #
-#
 # You can create multiple figures by using multiple
 # `~.pyplot.figure` calls with an increasing figure
 # number.  Of course, each figure can contain as many axes and subplots