From 6fc102094ec456148ebe13d869873950277ac55e Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 19 May 2026 12:15:12 +0200
Subject: [PATCH] DOC: Remove "Multiple lines using pyplot"

We should not promote the specific `plot(x, y, fmt, x2, y2, fmt)` anymore. This is a Matlabism and hard to read and reason about. Separate `plot()` calls are the better option. They don't need a dedicated pyplot example. Therefore, a redirect to the pyplot subplot example is sufficient, which as a side-topic has two plot calls in one subplot.

Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>
---
 galleries/examples/pyplots/pyplot_three.py    | 26 -------------------
 .../examples/pyplots/pyplot_two_subplots.py   | 15 ++++++++++-
 2 files changed, 14 insertions(+), 27 deletions(-)
 delete mode 100644 galleries/examples/pyplots/pyplot_three.py

diff --git a/galleries/examples/pyplots/pyplot_three.py b/galleries/examples/pyplots/pyplot_three.py
deleted file mode 100644
index b14998cca4c9..000000000000
--- a/galleries/examples/pyplots/pyplot_three.py
+++ /dev/null
@@ -1,26 +0,0 @@
-"""
-===========================
-Multiple lines using pyplot
-===========================
-
-Plot three datasets with a single call to `~matplotlib.pyplot.plot`.
-"""
-
-import matplotlib.pyplot as plt
-import numpy as np
-
-# evenly sampled time at 200ms intervals
-t = np.arange(0., 5., 0.2)
-
-# red dashes, blue squares and green triangles
-plt.plot(t, t, 'r--', t, t**2, 'bs', t, t**3, 'g^')
-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/galleries/examples/pyplots/pyplot_two_subplots.py b/galleries/examples/pyplots/pyplot_two_subplots.py
index 2eb0237d5521..b532c7b1534d 100644
--- a/galleries/examples/pyplots/pyplot_two_subplots.py
+++ b/galleries/examples/pyplots/pyplot_two_subplots.py
@@ -3,7 +3,18 @@
 Two subplots using pyplot
 =========================
 
-Create a figure with two subplots using `.pyplot.subplot`.
+A typical pyplot usage pattern is to create subplots incrementally through
+`~.pyplot.subplot`.
+
+The three-digit number passed to `~.pyplot.subplot` specifies the position of
+the subplot in the grid of subplots. ``211`` means "in a grid of 2 rows and 1 column,
+create this subplot in the 1st position". ``212`` likewise means "in a grid of 2
+rows and 1 column, create this subplot in the 2nd position".
+
+After calling ``subplot()`` all following pyplot commands will modify that subplot
+until a new subplot is created.
+
+.. redirect-from:: /gallery/pyplots/pyplot_three
 """
 
 import matplotlib.pyplot as plt
@@ -21,9 +32,11 @@ def f(t):
 plt.subplot(211)
 plt.plot(t1, f(t1), color='tab:blue', marker='o')
 plt.plot(t2, f(t2), color='black')
+plt.title("Subplot 1")
 
 plt.subplot(212)
 plt.plot(t2, np.cos(2*np.pi*t2), color='tab:orange', linestyle='--')
+plt.title("Subplot 2")
 plt.show()
 
 # %%