From cd0e1b5b84df2a8b793662735a75bc399d87c3e0 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Mon, 24 Aug 2020 23:39:28 +0200
Subject: [PATCH 1/3] Add a soft deprecation note to Axes.plot_date()

---
 lib/matplotlib/axes/_axes.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 7df953e83015..5f25db34cc20 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -1616,6 +1616,18 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
         """
         Plot co-ercing the axis to treat floats as dates.
 
+        .. note::
+
+            This method exists for historic reasons and will be deprecated in
+            the future.
+
+            - ``datetime``-like data should directly be plotted using
+              `~.Axes.plot`.
+            -  If you need to plot plain numeric data as :ref:`date-format` or
+               need to set a timezone, call ``ax.xaxis.axis_date`` /
+               ``ax.yaxis.axis_date`` before `~.Axes.plot`. See
+               `.Axis.axis_date`.
+
         Similar to `.plot`, this plots *y* vs. *x* as lines or markers.
         However, the axis labels are formatted as dates depending on *xdate*
         and *ydate*.  Note that `.plot` will work with `datetime` and

From d86112ac134e769057db5c284e0aabef39651b2a Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Mon, 24 Aug 2020 23:41:59 +0200
Subject: [PATCH 2/3] De-emphasize usage of Axes.plot_date() in the docs.

---
 examples/ticks_and_spines/date_demo_convert.py | 2 +-
 examples/ticks_and_spines/date_demo_rrule.py   | 2 +-
 lib/matplotlib/dates.py                        | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/ticks_and_spines/date_demo_convert.py b/examples/ticks_and_spines/date_demo_convert.py
index e1f266cbe09b..9d0b1695cb68 100644
--- a/examples/ticks_and_spines/date_demo_convert.py
+++ b/examples/ticks_and_spines/date_demo_convert.py
@@ -17,7 +17,7 @@
 y = np.arange(len(dates))
 
 fig, ax = plt.subplots()
-ax.plot_date(dates, y ** 2)
+ax.plot(dates, y**2, 'o')
 
 # this is superfluous, since the autoscaler should get it right, but
 # use date2num and num2date to convert between dates and floats if
diff --git a/examples/ticks_and_spines/date_demo_rrule.py b/examples/ticks_and_spines/date_demo_rrule.py
index d358f5731048..c020a44c375b 100644
--- a/examples/ticks_and_spines/date_demo_rrule.py
+++ b/examples/ticks_and_spines/date_demo_rrule.py
@@ -35,7 +35,7 @@
 
 
 fig, ax = plt.subplots()
-plt.plot_date(dates, s)
+plt.plot(dates, s, 'o')
 ax.xaxis.set_major_locator(loc)
 ax.xaxis.set_major_formatter(formatter)
 ax.xaxis.set_tick_params(rotation=30, labelsize=10)
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
index 45b4e51de9d8..b5befc97d397 100644
--- a/lib/matplotlib/dates.py
+++ b/lib/matplotlib/dates.py
@@ -85,7 +85,7 @@
 All the Matplotlib date converters, tickers and formatters are timezone aware.
 If no explicit timezone is provided, :rc:`timezone` is assumed.  If you want to
 use a custom time zone, pass a `datetime.tzinfo` instance with the tz keyword
-argument to `num2date`, `~.Axes.plot_date`, and any custom date tickers or
+argument to `num2date`, `.Axis.axis_date`, and any custom date tickers or
 locators you create.
 
 A wide range of specific and general purpose date tick locators and

From ef001b27b7721082aacac713f818acf9adf22466 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 25 Aug 2020 00:23:04 +0200
Subject: [PATCH 3/3] Discourage use of plot_date()

---
 doc/api/next_api_changes/deprecations/18346-TH.rst | 9 +++++++++
 lib/matplotlib/axes/_axes.py                       | 2 +-
 2 files changed, 10 insertions(+), 1 deletion(-)
 create mode 100644 doc/api/next_api_changes/deprecations/18346-TH.rst

diff --git a/doc/api/next_api_changes/deprecations/18346-TH.rst b/doc/api/next_api_changes/deprecations/18346-TH.rst
new file mode 100644
index 000000000000..c6348157e2b2
--- /dev/null
+++ b/doc/api/next_api_changes/deprecations/18346-TH.rst
@@ -0,0 +1,9 @@
+``plot_date``
+~~~~~~~~~~~~~
+The use of `~.Axes.plot_date` is discouraged. This method exists for historic
+reasons and may be deprecated in the future.
+
+- ``datetime``-like data should directly be plotted using `~.Axes.plot`.
+- If you need to plot plain numeric data as :ref:`date-format` or
+  need to set a timezone, call ``ax.xaxis.axis_date`` / ``ax.yaxis.axis_date``
+  before `~.Axes.plot`. See `.Axis.axis_date`.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 5f25db34cc20..bd140a0d90aa 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -1616,7 +1616,7 @@ def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
         """
         Plot co-ercing the axis to treat floats as dates.
 
-        .. note::
+        .. admonition:: Discouraged
 
             This method exists for historic reasons and will be deprecated in
             the future.