some cleanup of matplotlib.dates docs

timhoffm · timhoffm · commit 2076769c894e · 2018-01-14T03:03:24.000+01:00
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -1,11 +1,19 @@
 """
 Matplotlib provides sophisticated date plotting capabilities, standing on the
 shoulders of python :mod:`datetime`, the add-on modules :mod:`pytz` and
-:mod:`dateutil`.  :class:`datetime` objects are converted to floating point
-numbers which represent time in days since 0001-01-01 UTC, plus 1.  For
-example, 0001-01-01, 06:00 is 1.25, not 0.25.  The helper functions
-:func:`date2num`, :func:`num2date` and :func:`drange` are used to facilitate
-easy conversion to and from :mod:`datetime` and numeric ranges.
+:mod:`dateutil`.
+
+
+.. date-format:
+
+Matplotlib date format
+----------------------
+Matplotlib represents dates using floating point numbers specifying the number
+of days since 0001-01-01 UTC, plus 1.  For example, 0001-01-01, 06:00 is 1.25,
+not 0.25. Values < 1, i.e. dates before 0001-01-01 UTC are not supported.
+
+The helper functions :func:`date2num`, :func:`num2date` and :func:`drange` are
+used for easy conversion between :mod:`datetime` objects and Matplotlib dates.
 
 .. note::
 
@@ -20,24 +28,22 @@
    732403, whereas using the Gregorian calendar via the datetime
    module we find::
 
-     In [31]:date(2006,4,1).toordinal() - date(1,1,1).toordinal()
-     Out[31]:732401
+     In [1]: date(2006,4,1).toordinal() - date(1,1,1).toordinal()
+     Out[1]: 732401
 
+All the Matplotlib date converters, tickers and formatters are timezone aware.
+If no explicit timezone is provided, the rcParam ``timezone`` is assumend.  If
+you want to use a custom time zone, pass a :class:`pytz.timezone` instance
+with the tz keyword argument to :func:`num2date`, :func:`.plot_date`, and any
+custom date tickers or locators you create.
+See `pytz <http://pythonhosted.org/pytz/>`_ for information on :mod:`pytz` and
+timezone handling.
 
 A wide range of specific and general purpose date tick locators and
 formatters are provided in this module.  See
 :mod:`matplotlib.ticker` for general information on tick locators
 and formatters.  These are described below.
 
-All the matplotlib date converters, tickers and formatters are
-timezone aware, and the default timezone is given by the timezone
-parameter in your :file:`matplotlibrc` file.  If you leave out a
-:class:`tz` timezone instance, the default from your rc file will be
-assumed.  If you want to use a custom time zone, pass a
-:class:`pytz.timezone` instance with the tz keyword argument to
-:func:`num2date`, :func:`plot_date`, and any custom date tickers or
-locators you create.  See `pytz <http://pythonhosted.org/pytz/>`_ for
-information on :mod:`pytz` and timezone handling.
 
 The `dateutil module <https://dateutil.readthedocs.io/en/stable/>`_ provides
 additional code to handle date ticking, making it easy to place ticks
@@ -381,12 +387,11 @@ def datestr2num(d, default=None):
 
 def date2num(d):
     """
-    Converts datetime objects to Matplotlib dates.
+    Convert datetime objects to Matplotlib dates.
 
     Parameters
     ----------
-    d : :class:`datetime` or :class:`numpy.datetime64`, or sequences of
-        these classes.
+    d : `datetime.datetime` or `numpy.datetime64` or sequences of these
 
     Returns
     -------
@@ -415,11 +420,11 @@ def date2num(d):
 
 def julian2num(j):
     """
-    Convert a Julian date (or sequence) to a matplotlib date (or sequence).
+    Convert a Julian date (or sequence) to a Matplotlib date (or sequence).
 
     Parameters
     ----------
-    k : float or sequence of floats
+    j : float or sequence of floats
         Julian date(s)
 
     Returns
@@ -453,21 +458,23 @@ def num2julian(n):
 
 def num2date(x, tz=None):
     """
+    Convert Matplotlib dates to `~datetime.datetime` objects.
+
     Parameters
     ----------
     x : float or sequence of floats
         Number of days (fraction part represents hours, minutes, seconds)
         since 0001-01-01 00:00:00 UTC, plus one.
     tz : string, optional
-        Timezone of *x* (defaults to rcparams TZ value).
+        Timezone of *x* (defaults to rcparams ``timezone``).
 
     Returns
     -------
-    :class:`datetime` or sequence of :class:`datetime`
-        Dates are returned in timezone *tz*
+    `~datetime.datetime` or sequence of `~datetime.datetime`
+        Dates are returned in timezone *tz*.
 
-    If *x* is a sequence, a sequence of :class:`datetime` objects will
-    be returned.
+        If *x* is a sequence, a sequence of :class:`datetime` objects will
+        be returned.
 
     Notes
     -----
@@ -495,18 +502,19 @@ def _ordinalf_to_timedelta(x):
 
 def num2timedelta(x):
     """
-    Converts number of days to a :class:`timdelta` object.
+    Convert number of days to a :class:`timdelta` object.
+
     If *x* is a sequence, a sequence of :class:`timedelta` objects will
     be returned.
 
     Parameters
     ----------
     x : float, sequence of floats
-        Number of days (fraction part represents hours, minutes, seconds)
+        Number of days. The fraction part represents hours, minutes, seconds.
 
     Returns
     -------
-    :class:`timedelta` or list[:class:`timedelta`]
+    `.timedelta` or list[:class:`.timedelta`]
 
     """
     if not cbook.iterable(x):
@@ -520,9 +528,23 @@ def num2timedelta(x):
 
 def drange(dstart, dend, delta):
     """
-    Return a date range as float Gregorian ordinals.  *dstart* and
-    *dend* are :class:`datetime` instances.  *delta* is a
-    :class:`datetime.timedelta` instance.
+    Return a sequence of equally spaced Matplotlib dates.
+
+    The dates start at *dstart* and reach up to, but not including *dend*.
+    They are spaced by *delta*.
+
+    Parameters
+    ----------
+    dstart, dend : `~datetime.datetime`
+        The date limits.
+    delta : `datetime.timedelta`
+        Spacing of the dates.
+
+    Returns
+    -------
+    drange : `numpy.array`
+        A list floats representing Matplotlib dates.
+
     """
     f1 = date2num(dstart)
     f2 = date2num(dend)
