improve docstring of Axes.plot_date and parts of matplotlib.dates

Author: timhoffm

lib/matplotlib/axes/_axes.py

@@ -1381,64 +1381,66 @@ def plot(self, *args, **kwargs):
     def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False,
                   **kwargs):
         """
-        A plot with data that contains dates.
-
-        Similar to the :func:`~matplotlib.pyplot.plot` command, except
-        the *x* or *y* (or both) data is considered to be dates, and the
-        axis is labeled accordingly.
-
-        *x* and/or *y* can be a sequence of dates represented as float
-        days since 0001-01-01 UTC.
-
-        Note if you are using custom date tickers and formatters, it
-        may be necessary to set the formatters/locators after the call
-        to :meth:`plot_date` since :meth:`plot_date` will set the
-        default tick locator to
-        :class:`matplotlib.dates.AutoDateLocator` (if the tick
-        locator is not already set to a
-        :class:`matplotlib.dates.DateLocator` instance) and the
-        default tick formatter to
-        :class:`matplotlib.dates.AutoDateFormatter` (if the tick
-        formatter is not already set to a
-        :class:`matplotlib.dates.DateFormatter` instance).
+        Plot data that contains dates.
 
+        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*.
 
         Parameters
         ----------
-        fmt : string
-            The plot format string.
+        x, y : array-like
+            The coordinates of the data points. If *xdate* or *ydate* is
+            *True*, the respective values *x* or *y* are interpreted as
+            :ref:`Matplotlib dates <date-format>`.
+
+        fmt : str, optional
+            The plot format string. For details, see the corresponding
+            parameter in `.plot`.
 
         tz : [ *None* | timezone string | :class:`tzinfo` instance]
-            The time zone to use in labeling dates. If *None*, defaults to rc
-            value.
+            The time zone to use in labeling dates. If *None*, defaults to
+            rcParam ``timezone``.
 
-        xdate : boolean
-            If *True*, the *x*-axis will be labeled with dates.
+        xdate : bool, optional, default: True
+            If *True*, the *x*-axis will be interpreted as Matplotlib dates.
 
-        ydate : boolean
-            If *True*, the *y*-axis will be labeled with dates.
+        ydate : bool, optional, default: False
+            If *True*, the *y*-axis will be interpreted as Matplotlib dates.
 
 
         Returns
         -------
         lines
+            A list of `.Line2D` objects that were added to the axes.
 
 
-        See Also
-        --------
-        matplotlib.dates : helper functions on dates
-        matplotlib.dates.date2num : how to convert dates to num
-        matplotlib.dates.num2date : how to convert num to dates
-        matplotlib.dates.drange : how floating point dates
-
         Other Parameters
         ----------------
-        **kwargs :
+        **kwargs
             Keyword arguments control the :class:`~matplotlib.lines.Line2D`
             properties:
 
             %(Line2D)s
 
+
+        See Also
+        --------
+        matplotlib.dates : Helper functions on dates.
+        matplotlib.dates.date2num : Convert dates to num.
+        matplotlib.dates.num2date : Convert num to dates.
+        matplotlib.dates.drange : Create an equally spaced sequence of dates.
+
+
+        Notes
+        -----
+        If you are using custom date tickers and formatters, it may be
+        necessary to set the formatters/locators after the call to
+        `.plot_date`. `.plot_date` will set the default tick locator to
+        `.AutoDateLocator` (if the tick locator is not already set to a
+        `.DateLocator` instance) and the default tick formatter to
+        `.AutoDateFormatter` (if the tick formatter is not already set to a
+        `.DateFormatter` instance).
         """
 
         if not self._hold:

lib/matplotlib/dates.py

@@ -4,16 +4,29 @@
 :mod:`dateutil`.
 
 
-.. date-format:
+.. _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.
+There are a number of helper functions to convert between :mod:`datetime`
+objects and Matplotlib dates:
+
+.. currentmodule:: matplotlib.dates
+
+.. autosummary::
+   :nosignatures:
+
+   date2num
+   num2date
+   num2timedelta
+   epoch2num
+   num2epoch
+   mx2num
+   drange
 
 .. note::
 
@@ -28,7 +41,7 @@
    732403, whereas using the Gregorian calendar via the datetime
    module we find::
 
-     In [1]: date(2006,4,1).toordinal() - date(1,1,1).toordinal()
+     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.
@@ -467,9 +480,9 @@ def _ordinalf_to_timedelta(x):
 
 def num2timedelta(x):
     """
-    Convert number of days to a :class:`timdelta` object.
+    Convert number of days to a `~datetime.timedelta` object.
 
-    If *x* is a sequence, a sequence of :class:`timedelta` objects will
+    If *x* is a sequence, a sequence of `~datetime.timedelta` objects will
     be returned.
 
     Parameters
@@ -479,7 +492,7 @@ def num2timedelta(x):
 
     Returns
     -------
-    `.timedelta` or list[:class:`.timedelta`]
+    `datetime.timedelta` or list[`datetime.timedelta`]
 
     """
     if not cbook.iterable(x):