Merge pull request #21858 from meeseeksmachine/auto-backport-of-pr-21837-on-v3.5.0-doc

QuLogic · web-flow · commit 29d1b57c5b7d · 2021-12-03T22:45:13.000-05:00
Backport PR #21837 on branch v3.5.0-doc (Display example figures in a single column)
diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css
@@ -237,6 +237,11 @@ div.sphx-glr-download a:hover {
     background-color: #BCD4DF;
 }
 
+/* Do not fold multiple figures in examples into two column layout. */
+img.sphx-glr-multi-img {
+    max-width: 100%;
+}
+
 table.property-table th,
 table.property-table td {
     padding: 4px 10px;
diff --git a/examples/images_contours_and_fields/barb_demo.py b/examples/images_contours_and_fields/barb_demo.py
@@ -47,6 +47,7 @@
 masked_u[4] = 1000  # Bad value that should not be plotted when masked
 masked_u[4] = np.ma.masked
 
+#############################################################################
 # Identical plot to panel 2 in the first figure, but with the point at
 # (0.5, 0.25) missing (masked)
 fig2, ax2 = plt.subplots()
diff --git a/examples/images_contours_and_fields/contourf_demo.py b/examples/images_contours_and_fields/contourf_demo.py
@@ -33,10 +33,12 @@
 interior = np.sqrt(X**2 + Y**2) < 0.5
 Z[interior] = np.ma.masked
 
-# We are using automatic selection of contour levels;
-# this is usually not such a good idea, because they don't
-# occur on nice boundaries, but we do it here for purposes
-# of illustration.
+#############################################################################
+# Automatic contour levels
+# ------------------------
+# We are using automatic selection of contour levels; this is usually not such
+# a good idea, because they don't occur on nice boundaries, but we do it here
+# for purposes of illustration.
 
 fig1, ax2 = plt.subplots(constrained_layout=True)
 CS = ax2.contourf(X, Y, Z, 10, cmap=plt.cm.bone, origin=origin)
@@ -58,10 +60,13 @@
 # Add the contour line levels to the colorbar
 cbar.add_lines(CS2)
 
+#############################################################################
+# Explicit contour levels
+# -----------------------
+# Now make a contour plot with the levels specified, and with the colormap
+# generated automatically from a list of colors.
+
 fig2, ax2 = plt.subplots(constrained_layout=True)
-# Now make a contour plot with the levels specified,
-# and with the colormap generated automatically from a list
-# of colors.
 levels = [-1.5, -1, -0.5, 0, 0.5, 1]
 CS3 = ax2.contourf(X, Y, Z, levels,
                    colors=('r', 'g', 'b'),
@@ -84,6 +89,9 @@
 # needs from the ContourSet object, CS3.
 fig2.colorbar(CS3)
 
+#############################################################################
+# Extension settings
+# ------------------
 # Illustrate all 4 possible "extend" settings:
 extends = ["neither", "both", "min", "max"]
 cmap = plt.colormaps["winter"].with_extremes(under="magenta", over="yellow")
diff --git a/examples/images_contours_and_fields/image_demo.py b/examples/images_contours_and_fields/image_demo.py
@@ -46,28 +46,27 @@
 with cbook.get_sample_data('grace_hopper.jpg') as image_file:
     image = plt.imread(image_file)
 
-fig, ax = plt.subplots()
-ax.imshow(image)
-ax.axis('off')  # clear x-axis and y-axis
-
-
-# And another image
-
-# Data are 256x256 16-bit integers.
+# And another image, using 256x256 16-bit integers.
 w, h = 256, 256
 with cbook.get_sample_data('s1045.ima.gz') as datafile:
     s = datafile.read()
 A = np.frombuffer(s, np.uint16).astype(float).reshape((w, h))
-
-fig, ax = plt.subplots()
 extent = (0, 25, 0, 25)
-im = ax.imshow(A, cmap=plt.cm.hot, origin='upper', extent=extent)
+
+fig, ax = plt.subplot_mosaic([
+    ['hopper', 'mri']
+], figsize=(7, 3.5))
+
+ax['hopper'].imshow(image)
+ax['hopper'].axis('off')  # clear x-axis and y-axis
+
+im = ax['mri'].imshow(A, cmap=plt.cm.hot, origin='upper', extent=extent)
 
 markers = [(15.9, 14.5), (16.8, 15)]
 x, y = zip(*markers)
-ax.plot(x, y, 'o')
+ax['mri'].plot(x, y, 'o')
 
-ax.set_title('MRI')
+ax['mri'].set_title('MRI')
 
 plt.show()
 
diff --git a/examples/lines_bars_and_markers/fill_betweenx_demo.py b/examples/lines_bars_and_markers/fill_betweenx_demo.py
@@ -26,9 +26,12 @@
 ax3.fill_betweenx(y, x1, x2)
 ax3.set_title('between (x1, x2)')
 
-# now fill between x1 and x2 where a logical condition is met.  Note
-# this is different than calling
+#############################################################################
+# Now fill between x1 and x2 where a logical condition is met. Note this is
+# different than calling::
+#
 #   fill_between(y[where], x1[where], x2[where])
+#
 # because of edge effects over multiple contiguous regions.
 
 fig, [ax, ax1] = plt.subplots(1, 2, sharey=True, figsize=(6, 6))
@@ -44,9 +47,9 @@
 ax1.fill_betweenx(y, x1, x2, where=x2 <= x1, facecolor='red')
 ax1.set_title('regions with x2 > 1 are masked')
 
-# This example illustrates a problem; because of the data
-# gridding, there are undesired unfilled triangles at the crossover
-# points.  A brute-force solution would be to interpolate all
-# arrays to a very fine grid before plotting.
+#############################################################################
+# This example illustrates a problem; because of the data gridding, there are
+# undesired unfilled triangles at the crossover points. A brute-force solution
+# would be to interpolate all arrays to a very fine grid before plotting.
 
 plt.show()
diff --git a/examples/text_labels_and_annotations/accented_text.py b/examples/text_labels_and_annotations/accented_text.py
@@ -24,7 +24,8 @@
 ax.text(4, 0.5, r"$F=m\ddot{x}$")
 fig.tight_layout()
 
-# Unicode demo
+#############################################################################
+# You can also use Unicode characters directly in strings.
 fig, ax = plt.subplots()
 ax.set_title("GISCARD CHAHUTÉ À L'ASSEMBLÉE")
 ax.set_xlabel("LE COUP DE DÉ DE DE GAULLE")
diff --git a/examples/text_labels_and_annotations/annotation_demo.py b/examples/text_labels_and_annotations/annotation_demo.py
@@ -125,6 +125,7 @@
             horizontalalignment='left',
             verticalalignment='bottom')
 
+#############################################################################
 # You can also use polar notation on a cartesian axes.  Here the native
 # coordinate system ('data') is cartesian, so you need to specify the
 # xycoords and textcoords as 'polar' if you want to use (theta, radius).
@@ -230,6 +231,7 @@
 
 ax.set(xlim=(-1, 5), ylim=(-4, 3))
 
+#############################################################################
 # We'll create another figure so that it doesn't get too cluttered
 fig, ax = plt.subplots()
 
diff --git a/examples/ticks/tick-formatters.py b/examples/ticks/tick-formatters.py
@@ -34,12 +34,13 @@ def setup(ax, title):
             fontsize=14, fontname='Monospace', color='tab:blue')
 
 
+#############################################################################
 # Tick formatters can be set in one of two ways, either by passing a ``str``
 # or function to `~.Axis.set_major_formatter` or `~.Axis.set_minor_formatter`,
 # or by creating an instance of one of the various `~.ticker.Formatter` classes
 # and providing that to `~.Axis.set_major_formatter` or
 # `~.Axis.set_minor_formatter`.
-
+#
 # The first two examples directly pass a ``str`` or function.
 
 fig0, axs0 = plt.subplots(2, 1, figsize=(8, 2))
@@ -53,14 +54,15 @@ def setup(ax, title):
 
 # A function can also be used directly as a formatter. The function must take
 # two arguments: ``x`` for the tick value and ``pos`` for the tick position,
-# and must return a ``str``  This creates a FuncFormatter automatically.
+# and must return a ``str``. This creates a FuncFormatter automatically.
 setup(axs0[1], title="lambda x, pos: str(x-5)")
 axs0[1].xaxis.set_major_formatter(lambda x, pos: str(x-5))
 
 fig0.tight_layout()
 
 
-# The remaining examples use Formatter objects.
+#############################################################################
+# The remaining examples use `.Formatter` objects.
 
 fig1, axs1 = plt.subplots(7, 1, figsize=(8, 6))
 fig1.suptitle('Formatter Object Formatting')
diff --git a/examples/userdemo/demo_gridspec03.py b/examples/userdemo/demo_gridspec03.py
@@ -31,6 +31,7 @@ def annotate_axes(fig):
 
 annotate_axes(fig)
 
+#############################################################################
 
 fig = plt.figure()
 fig.suptitle("Controlling spacing around and between subplots")
