DOC: better intro for dates.py

jklymak · jklymak · commit 243f4402cde3 · 2021-02-27T21:59:26.000-08:00
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -2,6 +2,26 @@
 Matplotlib provides sophisticated date plotting capabilities, standing on the
 shoulders of python :mod:`datetime` and the add-on module :mod:`dateutil`.
 
+By default, Matpltolib uses the units machinery described in
+`~.matplotlib.units` to convert `datetime.datetime`, and `numpy.datetime64`
+objects when plotted on an x- or y-axis. By default, the user does not
+need to do anything for dates to be formatted, but dates often have strict
+formatting needs, so this module provides many axis locators and formatters.
+However, a basic example using `numpy.datetime64` is::
+
+    import numpy as np
+    fig, ax = plt.subplots()
+    times = np.arange(np.datetime64('2001-01-02'),
+                      np.datetime64('2002-02-03'), np.timedelta64(75, 'm'))
+    y = np.random.randn(len(times))
+    ax.plot(times, y)
+
+.. seealso::
+
+    - :doc:`/gallery/text_labels_and_annotations/date`
+    - :doc:`/gallery/ticks_and_spines/date_concise_formatter`
+    - :doc:`/gallery/ticks_and_spines/date_demo_convert`
+
 .. _date-format:
 
 Matplotlib date format
