Merge pull request matplotlib#26254 from StefRe/doc/date_fmt_loc

DOC: Improve readability of date formatters/locators example

Author: story645

galleries/examples/ticks/date_formatters_locators.py

@@ -18,27 +18,6 @@
                               WeekdayLocator, YearLocator, rrulewrapper)
 import matplotlib.ticker as ticker
 
-locators = [
-    # locator as str, xmax, fmt
-    ('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."""
@@ -55,13 +34,42 @@ def plot_axis(ax, locator=None, xmax='2002-02-01', fmt=None, formatter=None):
     ax.text(0.0, 0.2, locator or formatter, transform=ax.transAxes,
             fontsize=14, fontname='Monospace', color='tab:blue')
 
+# %%
+# :ref:`Date locators <date-tickers>`
+# -----------------------------------
+
+
+locators = [
+    # locator as str, xmax, fmt
+    ('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'),
+]
 
 fig, axs = plt.subplots(len(locators), 1, figsize=(8, len(locators) * .8),
                         layout='constrained')
 fig.suptitle('Date Locators')
 for ax, (locator, xmax, fmt) in zip(axs, locators):
     plot_axis(ax, locator, xmax, fmt)
 
+# %%
+# :ref:`date-formatters`
+# ----------------------
+
+formatters = [
+    'AutoDateFormatter(ax.xaxis.get_major_locator())',
+    'ConciseDateFormatter(ax.xaxis.get_major_locator())',
+    'DateFormatter("%b %Y")',
+]
+
 fig, axs = plt.subplots(len(formatters), 1, figsize=(8, len(formatters) * .8),
                         layout='constrained')
 fig.suptitle('Date Formatters')

lib/matplotlib/dates.py

@@ -99,6 +99,8 @@
 
 .. _dateutil: https://dateutil.readthedocs.io
 
+.. _date-tickers:
+
 Date tickers
 ------------
 
@@ -154,6 +156,8 @@
   4 hours, it will pick hours 0, 4, 8, etc. as ticks.  This behaviour is not
   guaranteed by default.
 
+.. _date-formatters:
+
 Date formatters
 ---------------