From 2f8c0fe0172c791d65190fe93ca0bf75c14b647a Mon Sep 17 00:00:00 2001
From: Steffen Rehberg <steffen.rehberg@googlemail.com>
Date: Mon, 6 Dec 2021 14:10:38 +0100
Subject: [PATCH] DOC: Add Date Tick Locators and Formatters example

---
 .flake8                                    |  1 +
 examples/ticks/date_formatters_locators.py | 92 ++++++++++++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 examples/ticks/date_formatters_locators.py

diff --git a/.flake8 b/.flake8
index ca1d8f2d4bdc..5ad3a331fba7 100644
--- a/.flake8
+++ b/.flake8
@@ -120,6 +120,7 @@ per-file-ignores =
     examples/subplots_axes_and_figures/demo_constrained_layout.py: E402
     examples/text_labels_and_annotations/custom_legends.py: E402
     examples/ticks/date_concise_formatter.py: E402
+    examples/ticks/date_formatters_locators.py: F401
     examples/user_interfaces/embedding_in_gtk3_panzoom_sgskip.py: E402
     examples/user_interfaces/embedding_in_gtk3_sgskip.py: E402
     examples/user_interfaces/embedding_in_gtk4_panzoom_sgskip.py: E402
diff --git a/examples/ticks/date_formatters_locators.py b/examples/ticks/date_formatters_locators.py
new file mode 100644
index 000000000000..9d765c238470
--- /dev/null
+++ b/examples/ticks/date_formatters_locators.py
@@ -0,0 +1,92 @@
+"""
+=================================
+Date tick locators and formatters
+=================================
+
+This example illustrates the usage and effect of the various date locators and
+formatters.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+from matplotlib.dates import (AutoDateLocator, YearLocator, MonthLocator,
+                              DayLocator, WeekdayLocator, HourLocator,
+                              MinuteLocator, SecondLocator, MicrosecondLocator,
+                              RRuleLocator, rrulewrapper, MONTHLY,
+                              MO, TU, WE, TH, FR, SA, SU, DateFormatter,
+                              AutoDateFormatter, ConciseDateFormatter)
+
+locators = [
+    ('AutoDateLocator(maxticks=8)', '2003-02-01', '%Y-%m'),
+    ('YearLocator(month=4)', '2003-02-01', '%Y-%m'),
+    ('MonthLocator(bymonth=[4,8,12])', '2003-02-01', '%Y-%m'),
+    ('DayLocator(interval=180)', '2003-02-01', '%Y-%m-%d'),
+    ('WeekdayLocator(byweekday=SU, interval=4)', '2000-07-01', '%a %Y-%m-%d'),
+    ('HourLocator(byhour=range(0,24,6))', '2000-02-04', '%H h'),
+    ('MinuteLocator(interval=15)', '2000-02-01 02:00', '%H:%M'),
+    ('SecondLocator(bysecond=(0,30))', '2000-02-01 00:02', '%H:%M:%S'),
+    ('MicrosecondLocator(interval=1000)', '2000-02-01 00:00:00.005', '%S.%f'),
+    ('RRuleLocator(rrulewrapper(freq=MONTHLY, \nbyweekday=(MO, TU, WE, TH,' +
+     ' FR), bysetpos=-1))', '2000-07-01', '%Y-%m-%d')
+]
+
+formatters = [
+    ('AutoDateFormatter(ax.xaxis.get_major_locator())'),
+    ('ConciseDateFormatter(ax.xaxis.get_major_locator())'),
+    ('DateFormatter("%b %Y")')
+]
+
+
+def plot_axis(ax, locator=None, xmax='2002-02-01', fmt=None, formatter=None):
+    """Set up common parameters for the Axes in the example."""
+    ax.spines.right.set_visible(False)
+    ax.spines.left.set_visible(False)
+    ax.spines.top.set_visible(False)
+    ax.yaxis.set_major_locator(ticker.NullLocator())
+    ax.tick_params(which='major', width=1.00, length=5)
+    ax.tick_params(which='minor', width=0.75, length=2.5)
+    ax.set_xlim(np.datetime64('2000-02-01'), np.datetime64(xmax))
+    if locator:
+        ax.xaxis.set_major_locator(eval(locator))
+        ax.xaxis.set_major_formatter(DateFormatter(fmt))
+    else:
+        ax.xaxis.set_major_formatter(eval(formatter))
+    ax.text(0.0, 0.2, locator or formatter, transform=ax.transAxes,
+            fontsize=14, fontname='Monospace', color='tab:blue')
+
+
+fig, ax = plt.subplots(len(locators), 1, figsize=(8, len(locators) * .8),
+                       layout='constrained')
+fig.suptitle('Date Locators')
+for i, loc in enumerate(locators):
+    plot_axis(ax[i], *loc)
+
+fig, ax = plt.subplots(len(formatters), 1, figsize=(8, len(formatters) * .8),
+                       layout='constrained')
+fig.suptitle('Date Formatters')
+for i, fmt in enumerate(formatters):
+    plot_axis(ax[i], formatter=fmt)
+
+
+#############################################################################
+#
+# .. admonition:: References
+#
+#    The use of the following functions, methods, classes and modules is shown
+#    in this example:
+#
+#    - `matplotlib.dates.AutoDateLocator`
+#    - `matplotlib.dates.YearLocator`
+#    - `matplotlib.dates.MonthLocator`
+#    - `matplotlib.dates.DayLocator`
+#    - `matplotlib.dates.WeekdayLocator`
+#    - `matplotlib.dates.HourLocator`
+#    - `matplotlib.dates.MinuteLocator`
+#    - `matplotlib.dates.SecondLocator`
+#    - `matplotlib.dates.MicrosecondLocator`
+#    - `matplotlib.dates.RRuleLocator`
+#    - `matplotlib.dates.rrulewrapper`
+#    - `matplotlib.dates.DateFormatter`
+#    - `matplotlib.dates.AutoDateFormatter`
+#    - `matplotlib.dates.ConciseDateFormatter`