From 80698784acd6c5d9ff708ff5e0575803dfde532e Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sun, 2 Oct 2022 18:37:58 +0200
Subject: [PATCH] Backport PR #24054:  DOC: Move OO-examples from pyplot
 section

---
 doc/users/faq/howto_faq.rst                   |  6 +-
 examples/{pyplots => misc}/fig_x.py           |  2 +
 examples/pyplots/boxplot_demo_pyplot.py       | 89 -------------------
 examples/pyplots/fig_axes_labels_simple.py    | 42 ---------
 examples/pyplots/pyplot_formatstr.py          | 21 -----
 examples/pyplots/pyplot_simple.py             |  9 +-
 examples/pyplots/text_layout.py               | 63 -------------
 examples/statistics/boxplot_demo.py           |  2 +
 .../auto_subplots_adjust.py                   |  2 +
 .../align_ylabels.py                          |  1 +
 .../annotate_transform.py                     |  2 +
 .../annotation_basic.py                       |  2 +
 .../annotation_polar.py                       |  2 +
 .../text_alignment.py                         |  2 +
 .../text_commands.py                          |  2 +
 examples/{pyplots => ticks}/dollar_ticks.py   |  2 +
 .../fig_axes_customize_simple.py              |  2 +
 examples/ticks/tick-formatters.py             |  1 +
 tutorials/intermediate/artists.py             |  2 +-
 tutorials/text/annotations.py                 |  8 +-
 20 files changed, 37 insertions(+), 225 deletions(-)
 rename examples/{pyplots => misc}/fig_x.py (93%)
 delete mode 100644 examples/pyplots/boxplot_demo_pyplot.py
 delete mode 100644 examples/pyplots/fig_axes_labels_simple.py
 delete mode 100644 examples/pyplots/pyplot_formatstr.py
 delete mode 100644 examples/pyplots/text_layout.py
 rename examples/{pyplots => subplots_axes_and_figures}/auto_subplots_adjust.py (98%)
 rename examples/{pyplots => text_labels_and_annotations}/align_ylabels.py (97%)
 rename examples/{pyplots => text_labels_and_annotations}/annotate_transform.py (96%)
 rename examples/{pyplots => text_labels_and_annotations}/annotation_basic.py (94%)
 rename examples/{pyplots => text_labels_and_annotations}/annotation_polar.py (95%)
 rename examples/{pyplots => text_labels_and_annotations}/text_commands.py (96%)
 rename examples/{pyplots => ticks}/dollar_ticks.py (94%)
 rename examples/{pyplots => ticks}/fig_axes_customize_simple.py (95%)

diff --git a/doc/users/faq/howto_faq.rst b/doc/users/faq/howto_faq.rst
index 4f60b9e14fe3..4ea220d969b0 100644
--- a/doc/users/faq/howto_faq.rst
+++ b/doc/users/faq/howto_faq.rst
@@ -187,7 +187,7 @@ multiple ways to fix this:
   - tight layout (:doc:`/tutorials/intermediate/tight_layout_guide`)
 
 - Calculate good values from the size of the plot elements yourself
-  (:doc:`/gallery/pyplots/auto_subplots_adjust`)
+  (:doc:`/gallery/subplots_axes_and_figures/auto_subplots_adjust`)
 
 .. _howto-align-label:
 
@@ -203,8 +203,8 @@ behavior by specifying the coordinates of the label.  The example
 below shows the default behavior in the left subplots, and the manual
 setting in the right subplots.
 
-.. figure:: ../../gallery/pyplots/images/sphx_glr_align_ylabels_001.png
-   :target: ../../gallery/pyplots/align_ylabels.html
+.. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_align_ylabels_001.png
+   :target: ../../gallery/text_labels_and_annotations/align_ylabels.html
    :align: center
    :scale: 50
 
diff --git a/examples/pyplots/fig_x.py b/examples/misc/fig_x.py
similarity index 93%
rename from examples/pyplots/fig_x.py
rename to examples/misc/fig_x.py
index 9ca5a3b13d8a..eaa16d80fa35 100644
--- a/examples/pyplots/fig_x.py
+++ b/examples/misc/fig_x.py
@@ -4,6 +4,8 @@
 =======================
 
 Adding lines to a figure without any axes.
+
+.. redirect-from:: /gallery/pyplots/fig_x
 """
 
 import matplotlib.pyplot as plt
diff --git a/examples/pyplots/boxplot_demo_pyplot.py b/examples/pyplots/boxplot_demo_pyplot.py
deleted file mode 100644
index 501eb2cf3447..000000000000
--- a/examples/pyplots/boxplot_demo_pyplot.py
+++ /dev/null
@@ -1,89 +0,0 @@
-"""
-============
-Boxplot Demo
-============
-
-Example boxplot code
-"""
-
-import numpy as np
-import matplotlib.pyplot as plt
-
-# Fixing random state for reproducibility
-np.random.seed(19680801)
-
-# fake up some data
-spread = np.random.rand(50) * 100
-center = np.ones(25) * 50
-flier_high = np.random.rand(10) * 100 + 100
-flier_low = np.random.rand(10) * -100
-data = np.concatenate((spread, center, flier_high, flier_low))
-
-###############################################################################
-
-fig1, ax1 = plt.subplots()
-ax1.set_title('Basic Plot')
-ax1.boxplot(data)
-
-###############################################################################
-
-fig2, ax2 = plt.subplots()
-ax2.set_title('Notched boxes')
-ax2.boxplot(data, notch=True)
-
-###############################################################################
-
-green_diamond = dict(markerfacecolor='g', marker='D')
-fig3, ax3 = plt.subplots()
-ax3.set_title('Changed Outlier Symbols')
-ax3.boxplot(data, flierprops=green_diamond)
-
-###############################################################################
-
-fig4, ax4 = plt.subplots()
-ax4.set_title('Hide Outlier Points')
-ax4.boxplot(data, showfliers=False)
-
-###############################################################################
-
-red_square = dict(markerfacecolor='r', marker='s')
-fig5, ax5 = plt.subplots()
-ax5.set_title('Horizontal Boxes')
-ax5.boxplot(data, vert=False, flierprops=red_square)
-
-###############################################################################
-
-fig6, ax6 = plt.subplots()
-ax6.set_title('Shorter Whisker Length')
-ax6.boxplot(data, flierprops=red_square, vert=False, whis=0.75)
-
-###############################################################################
-# Fake up some more data
-
-spread = np.random.rand(50) * 100
-center = np.ones(25) * 40
-flier_high = np.random.rand(10) * 100 + 100
-flier_low = np.random.rand(10) * -100
-d2 = np.concatenate((spread, center, flier_high, flier_low))
-
-###############################################################################
-# Making a 2-D array only works if all the columns are the
-# same length.  If they are not, then use a list instead.
-# This is actually more efficient because boxplot converts
-# a 2-D array into a list of vectors internally anyway.
-
-data = [data, d2, d2[::2]]
-fig7, ax7 = plt.subplots()
-ax7.set_title('Multiple Samples with Different sizes')
-ax7.boxplot(data)
-
-plt.show()
-
-#############################################################################
-#
-# .. admonition:: References
-#
-#    The use of the following functions, methods, classes and modules is shown
-#    in this example:
-#
-#    - `matplotlib.axes.Axes.boxplot` / `matplotlib.pyplot.boxplot`
diff --git a/examples/pyplots/fig_axes_labels_simple.py b/examples/pyplots/fig_axes_labels_simple.py
deleted file mode 100644
index 353f09477dfd..000000000000
--- a/examples/pyplots/fig_axes_labels_simple.py
+++ /dev/null
@@ -1,42 +0,0 @@
-"""
-==================
-Simple axes labels
-==================
-
-Label the axes of a plot.
-"""
-import numpy as np
-import matplotlib.pyplot as plt
-
-fig = plt.figure()
-fig.subplots_adjust(top=0.8)
-ax1 = fig.add_subplot(211)
-ax1.set_ylabel('Voltage [V]')
-ax1.set_title('A sine wave')
-
-t = np.arange(0.0, 1.0, 0.01)
-s = np.sin(2 * np.pi * t)
-line, = ax1.plot(t, s, lw=2)
-
-# Fixing random state for reproducibility
-np.random.seed(19680801)
-
-ax2 = fig.add_axes([0.15, 0.1, 0.7, 0.3])
-n, bins, patches = ax2.hist(np.random.randn(1000), 50)
-ax2.set_xlabel('Time [s]')
-
-plt.show()
-
-#############################################################################
-#
-# .. admonition:: References
-#
-#    The use of the following functions, methods, classes and modules is shown
-#    in this example:
-#
-#    - `matplotlib.axes.Axes.set_xlabel`
-#    - `matplotlib.axes.Axes.set_ylabel`
-#    - `matplotlib.axes.Axes.set_title`
-#    - `matplotlib.axes.Axes.plot`
-#    - `matplotlib.axes.Axes.hist`
-#    - `matplotlib.figure.Figure.add_axes`
diff --git a/examples/pyplots/pyplot_formatstr.py b/examples/pyplots/pyplot_formatstr.py
deleted file mode 100644
index e9be3830ec98..000000000000
--- a/examples/pyplots/pyplot_formatstr.py
+++ /dev/null
@@ -1,21 +0,0 @@
-"""
-====================
-plot() format string
-====================
-
-Use a format string (here, 'ro') to set the color and markers of a
-`~matplotlib.axes.Axes.plot`.
-"""
-
-import matplotlib.pyplot as plt
-plt.plot([1, 2, 3, 4], [1, 4, 9, 16], 'ro')
-plt.show()
-
-#############################################################################
-#
-# .. admonition:: References
-#
-#    The use of the following functions, methods, classes and modules is shown
-#    in this example:
-#
-#    - `matplotlib.axes.Axes.plot` / `matplotlib.pyplot.plot`
diff --git a/examples/pyplots/pyplot_simple.py b/examples/pyplots/pyplot_simple.py
index 414e5ae4f7ab..1a3b457acedd 100644
--- a/examples/pyplots/pyplot_simple.py
+++ b/examples/pyplots/pyplot_simple.py
@@ -5,10 +5,15 @@
 
 A very simple pyplot where a list of numbers are plotted against their
 index. Creates a straight line due to the rate of change being 1 for
-both the X and Y axis.
+both the X and Y axis. Use a format string (here, 'o-r') to set the
+markers (circles), linestyle (solid line) and color (red).
+
+.. redirect-from:: /gallery/pyplots/fig_axes_labels_simple
+.. redirect-from:: /gallery/pyplots/pyplot_formatstr
 """
 import matplotlib.pyplot as plt
-plt.plot([1, 2, 3, 4])
+
+plt.plot([1, 2, 3, 4], 'o-r')
 plt.ylabel('some numbers')
 plt.show()
 
diff --git a/examples/pyplots/text_layout.py b/examples/pyplots/text_layout.py
deleted file mode 100644
index 641aa77320a5..000000000000
--- a/examples/pyplots/text_layout.py
+++ /dev/null
@@ -1,63 +0,0 @@
-"""
-===========
-Text Layout
-===========
-
-Create text with different alignment and rotation.
-"""
-
-import matplotlib.pyplot as plt
-import matplotlib.patches as patches
-
-fig = plt.figure()
-
-left, width = .25, .5
-bottom, height = .25, .5
-right = left + width
-top = bottom + height
-
-# Draw a rectangle in figure coordinates ((0, 0) is bottom left and (1, 1) is
-# upper right).
-p = patches.Rectangle((left, bottom), width, height, fill=False)
-fig.add_artist(p)
-
-# Figure.text (aka. plt.figtext) behaves like Axes.text (aka. plt.text), with
-# the sole exception that the coordinates are relative to the figure ((0, 0) is
-# bottom left and (1, 1) is upper right).
-fig.text(left, bottom, 'left top',
-         horizontalalignment='left', verticalalignment='top')
-fig.text(left, bottom, 'left bottom',
-         horizontalalignment='left', verticalalignment='bottom')
-fig.text(right, top, 'right bottom',
-         horizontalalignment='right', verticalalignment='bottom')
-fig.text(right, top, 'right top',
-         horizontalalignment='right', verticalalignment='top')
-fig.text(right, bottom, 'center top',
-         horizontalalignment='center', verticalalignment='top')
-fig.text(left, 0.5*(bottom+top), 'right center',
-         horizontalalignment='right', verticalalignment='center',
-         rotation='vertical')
-fig.text(left, 0.5*(bottom+top), 'left center',
-         horizontalalignment='left', verticalalignment='center',
-         rotation='vertical')
-fig.text(0.5*(left+right), 0.5*(bottom+top), 'middle',
-         horizontalalignment='center', verticalalignment='center',
-         fontsize=20, color='red')
-fig.text(right, 0.5*(bottom+top), 'centered',
-         horizontalalignment='center', verticalalignment='center',
-         rotation='vertical')
-fig.text(left, top, 'rotated\nwith newlines',
-         horizontalalignment='center', verticalalignment='center',
-         rotation=45)
-
-plt.show()
-
-#############################################################################
-#
-# .. admonition:: References
-#
-#    The use of the following functions, methods, classes and modules is shown
-#    in this example:
-#
-#    - `matplotlib.figure.Figure.add_artist`
-#    - `matplotlib.figure.Figure.text`
diff --git a/examples/statistics/boxplot_demo.py b/examples/statistics/boxplot_demo.py
index 0ad146aa1d2d..252ca25bd58d 100644
--- a/examples/statistics/boxplot_demo.py
+++ b/examples/statistics/boxplot_demo.py
@@ -8,6 +8,8 @@
 The following examples show off how to visualize boxplots with
 Matplotlib. There are many options to control their appearance and
 the statistics that they use to summarize the data.
+
+.. redirect-from:: /gallery/pyplots/boxplot_demo_pyplot
 """
 
 import matplotlib.pyplot as plt
diff --git a/examples/pyplots/auto_subplots_adjust.py b/examples/subplots_axes_and_figures/auto_subplots_adjust.py
similarity index 98%
rename from examples/pyplots/auto_subplots_adjust.py
rename to examples/subplots_axes_and_figures/auto_subplots_adjust.py
index b4c731cb4cdc..bd6326b8291f 100644
--- a/examples/pyplots/auto_subplots_adjust.py
+++ b/examples/subplots_axes_and_figures/auto_subplots_adjust.py
@@ -36,6 +36,8 @@
 This function is executed after the figure has been drawn. It can now check
 if the subplot leaves enough room for the text. If not, the subplot parameters
 are updated and second draw is triggered.
+
+.. redirect-from:: /gallery/pyplots/auto_subplots_adjust
 """
 
 import matplotlib.pyplot as plt
diff --git a/examples/pyplots/align_ylabels.py b/examples/text_labels_and_annotations/align_ylabels.py
similarity index 97%
rename from examples/pyplots/align_ylabels.py
rename to examples/text_labels_and_annotations/align_ylabels.py
index 3523e08f93fd..8e47909cc6c1 100644
--- a/examples/pyplots/align_ylabels.py
+++ b/examples/text_labels_and_annotations/align_ylabels.py
@@ -6,6 +6,7 @@
 Two methods are shown here, one using a short call to `.Figure.align_ylabels`
 and the second a manual way to align the labels.
 
+.. redirect-from:: /gallery/pyplots/align_ylabels
 """
 import numpy as np
 import matplotlib.pyplot as plt
diff --git a/examples/pyplots/annotate_transform.py b/examples/text_labels_and_annotations/annotate_transform.py
similarity index 96%
rename from examples/pyplots/annotate_transform.py
rename to examples/text_labels_and_annotations/annotate_transform.py
index 9d3d09f5a0ba..1145f7fdb9a2 100644
--- a/examples/pyplots/annotate_transform.py
+++ b/examples/text_labels_and_annotations/annotate_transform.py
@@ -6,6 +6,8 @@
 This example shows how to use different coordinate systems for annotations.
 For a complete overview of the annotation capabilities, also see the
 :doc:`annotation tutorial</tutorials/text/annotations>`.
+
+.. redirect-from:: /gallery/pyplots/annotate_transform
 """
 
 import numpy as np
diff --git a/examples/pyplots/annotation_basic.py b/examples/text_labels_and_annotations/annotation_basic.py
similarity index 94%
rename from examples/pyplots/annotation_basic.py
rename to examples/text_labels_and_annotations/annotation_basic.py
index 5a6327b48748..d9ea9748197f 100644
--- a/examples/pyplots/annotation_basic.py
+++ b/examples/text_labels_and_annotations/annotation_basic.py
@@ -8,6 +8,8 @@
 
 For a complete overview of the annotation capabilities, also see the
 :doc:`annotation tutorial</tutorials/text/annotations>`.
+
+.. redirect-from:: /gallery/pyplots/annotation_basic
 """
 import numpy as np
 import matplotlib.pyplot as plt
diff --git a/examples/pyplots/annotation_polar.py b/examples/text_labels_and_annotations/annotation_polar.py
similarity index 95%
rename from examples/pyplots/annotation_polar.py
rename to examples/text_labels_and_annotations/annotation_polar.py
index 24a3a20bc3fe..a7f8b764d914 100644
--- a/examples/pyplots/annotation_polar.py
+++ b/examples/text_labels_and_annotations/annotation_polar.py
@@ -7,6 +7,8 @@
 
 For a complete overview of the annotation capabilities, also see the
 :doc:`annotation tutorial</tutorials/text/annotations>`.
+
+.. redirect-from:: /gallery/pyplots/annotation_polar
 """
 import numpy as np
 import matplotlib.pyplot as plt
diff --git a/examples/text_labels_and_annotations/text_alignment.py b/examples/text_labels_and_annotations/text_alignment.py
index a12002972233..a748481d5261 100644
--- a/examples/text_labels_and_annotations/text_alignment.py
+++ b/examples/text_labels_and_annotations/text_alignment.py
@@ -6,6 +6,8 @@
 Texts are aligned relative to their anchor point depending on the properties
 ``horizontalalignment`` and ``verticalalignment``.
 
+.. redirect-from:: /gallery/pyplots/text_layout
+
 .. plot::
 
     import matplotlib.pyplot as plt
diff --git a/examples/pyplots/text_commands.py b/examples/text_labels_and_annotations/text_commands.py
similarity index 96%
rename from examples/pyplots/text_commands.py
rename to examples/text_labels_and_annotations/text_commands.py
index a13532246f0a..cb6d5413f8d4 100644
--- a/examples/pyplots/text_commands.py
+++ b/examples/text_labels_and_annotations/text_commands.py
@@ -4,6 +4,8 @@
 =============
 
 Plotting text of many different kinds.
+
+.. redirect-from:: /gallery/pyplots/text_commands
 """
 
 import matplotlib.pyplot as plt
diff --git a/examples/pyplots/dollar_ticks.py b/examples/ticks/dollar_ticks.py
similarity index 94%
rename from examples/pyplots/dollar_ticks.py
rename to examples/ticks/dollar_ticks.py
index 1f99ccdd674d..694e613db08d 100644
--- a/examples/pyplots/dollar_ticks.py
+++ b/examples/ticks/dollar_ticks.py
@@ -4,6 +4,8 @@
 ============
 
 Use a `~.ticker.FormatStrFormatter` to prepend dollar signs on y axis labels.
+
+.. redirect-from:: /gallery/pyplots/dollar_ticks
 """
 import numpy as np
 import matplotlib.pyplot as plt
diff --git a/examples/pyplots/fig_axes_customize_simple.py b/examples/ticks/fig_axes_customize_simple.py
similarity index 95%
rename from examples/pyplots/fig_axes_customize_simple.py
rename to examples/ticks/fig_axes_customize_simple.py
index b557feb961aa..74742f718939 100644
--- a/examples/pyplots/fig_axes_customize_simple.py
+++ b/examples/ticks/fig_axes_customize_simple.py
@@ -4,6 +4,8 @@
 =========================
 
 Customize the background, labels and ticks of a simple plot.
+
+.. redirect-from:: /gallery/pyplots/fig_axes_customize_simple
 """
 
 import matplotlib.pyplot as plt
diff --git a/examples/ticks/tick-formatters.py b/examples/ticks/tick-formatters.py
index ea9dc214fbb0..ac118cbfce03 100644
--- a/examples/ticks/tick-formatters.py
+++ b/examples/ticks/tick-formatters.py
@@ -7,6 +7,7 @@
 is formatted as a string.
 
 This example illustrates the usage and effect of the most common formatters.
+
 """
 
 import matplotlib.pyplot as plt
diff --git a/tutorials/intermediate/artists.py b/tutorials/intermediate/artists.py
index e2cf55fd5992..0078813f9edd 100644
--- a/tutorials/intermediate/artists.py
+++ b/tutorials/intermediate/artists.py
@@ -719,6 +719,6 @@ class in the Matplotlib API, and the one you will be working with most
 # dollar signs and colors them green on the right side of the yaxis.
 #
 #
-# .. include:: ../../gallery/pyplots/dollar_ticks.rst
+# .. include:: ../../gallery/ticks/dollar_ticks.rst
 #    :start-after: y axis labels.
 #    :end-before: .. admonition:: References
diff --git a/tutorials/text/annotations.py b/tutorials/text/annotations.py
index df2dda7ad580..7ab582d9f20f 100644
--- a/tutorials/text/annotations.py
+++ b/tutorials/text/annotations.py
@@ -25,8 +25,8 @@
 # *xy* and the location of the text *xytext*.  Both of these
 # arguments are ``(x, y)`` tuples.
 #
-# .. figure:: ../../gallery/pyplots/images/sphx_glr_annotation_basic_001.png
-#    :target: ../../gallery/pyplots/annotation_basic.html
+# .. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_annotation_basic_001.png
+#    :target: ../../gallery/text_labels_and_annotations/annotation_basic.html
 #    :align: center
 #
 # In this example, both the *xy* (arrow tip) and *xytext* locations
@@ -86,8 +86,8 @@
 # *fontsize* are passed from `~matplotlib.axes.Axes.annotate` to the
 # ``Text`` instance.
 #
-# .. figure:: ../../gallery/pyplots/images/sphx_glr_annotation_polar_001.png
-#    :target: ../../gallery/pyplots/annotation_polar.html
+# .. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_annotation_polar_001.png
+#    :target: ../../gallery/text_labels_and_annotations/annotation_polar.html
 #    :align: center
 #
 # For more on all the wild and wonderful things you can do with