Backport PR #15683: Cleanup dates.py docstrings.

timhoffm · MeeseeksDev[bot] · commit 79d77a96dc53 · 2019-11-18T22:13:39.000Z
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -127,7 +127,7 @@
   and to make the format as compact as possible while still having complete
   date information.  This is most useful when used with the `AutoDateLocator`.
 
-* `DateFormatter`: use `strftime` format strings.
+* `DateFormatter`: use `~datetime.datetime.strftime` format strings.
 
 * `IndexDateFormatter`: date plots with implicit *x* indexing.
 """
@@ -585,7 +585,8 @@ def drange(dstart, dend, delta):
 
 class DateFormatter(ticker.Formatter):
     """
-    Format a tick (in seconds since the epoch) with a `strftime` format string.
+    Format a tick (in days since the epoch) with a
+    `~datetime.datetime.strftime` format string.
     """
 
     illegal_s = re.compile(r"((^|[^%])(%%)*%s)")
@@ -595,8 +596,9 @@ def __init__(self, fmt, tz=None):
         Parameters
         ----------
         fmt : str
-            `strftime` format string
-        tz : `tzinfo`
+            `~datetime.datetime.strftime` format string
+        tz : `tzinfo`, default: :rc:`timezone`
+            Ticks timezone.
         """
         if tz is None:
             tz = _get_rc_timezone()
@@ -616,14 +618,12 @@ def set_tzinfo(self, tz):
 
 
 class IndexDateFormatter(ticker.Formatter):
-    """
-    Use with :class:`~matplotlib.ticker.IndexLocator` to cycle format
-    strings by index.
-    """
+    """Use with `.IndexLocator` to cycle format strings by index."""
+
     def __init__(self, t, fmt, tz=None):
         """
         *t* is a sequence of dates (floating point days).  *fmt* is a
-        :func:`strftime` format string.
+        `~datetime.datetime.strftime` format string.
         """
         if tz is None:
             tz = _get_rc_timezone()
@@ -643,8 +643,7 @@ class ConciseDateFormatter(ticker.Formatter):
     """
     This class attempts to figure out the best format to use for the
     date, and to make it as compact as possible, but still be complete. This is
-    most useful when used with the :class:`AutoDateLocator`::
-
+    most useful when used with the `AutoDateLocator`::
 
     >>> locator = AutoDateLocator()
     >>> formatter = ConciseDateFormatter(locator)
@@ -841,7 +840,7 @@ def format_data_short(self, value):
 class AutoDateFormatter(ticker.Formatter):
     """
     This class attempts to figure out the best format to use.  This is
-    most useful when used with the :class:`AutoDateLocator`.
+    most useful when used with the `AutoDateLocator`.
 
     The AutoDateFormatter has a scale dictionary that maps the scale
     of the tick (the distance in days between one major tick) and a
@@ -867,10 +866,9 @@ class AutoDateFormatter(ticker.Formatter):
     >>> formatter = AutoDateFormatter(locator)
     >>> formatter.scaled[1/(24.*60.)] = '%M:%S' # only show min and sec
 
-    A custom :class:`~matplotlib.ticker.FuncFormatter` can also be used.
-    The following example shows how to use a custom format function to strip
-    trailing zeros from decimal seconds and adds the date to the first
-    ticklabel::
+    A custom `.FuncFormatter` can also be used.  The following example shows
+    how to use a custom format function to strip trailing zeros from decimal
+    seconds and adds the date to the first ticklabel::
 
         >>> def my_format_function(x, pos=None):
         ...     x = matplotlib.dates.num2date(x)
@@ -1240,57 +1238,62 @@ def autoscale(self):
 
 class AutoDateLocator(DateLocator):
     """
-    On autoscale, this class picks the best
-    :class:`DateLocator` to set the view limits and the tick
-    locations.
-    """
-    def __init__(self, tz=None, minticks=5, maxticks=None,
-                 interval_multiples=True):
-        """
-        *minticks* is the minimum number of ticks desired, which is used to
-        select the type of ticking (yearly, monthly, etc.).
+    On autoscale, this class picks the best `DateLocator` to set the view
+    limits and the tick locations.
 
-        *maxticks* is the maximum number of ticks desired, which controls
-        any interval between ticks (ticking every other, every 3, etc.).
-        For really fine-grained control, this can be a dictionary mapping
-        individual rrule frequency constants (YEARLY, MONTHLY, etc.)
-        to their own maximum number of ticks.  This can be used to keep
-        the number of ticks appropriate to the format chosen in
-        :class:`AutoDateFormatter`. Any frequency not specified in this
-        dictionary is given a default value.
-
-        *tz* is a :class:`tzinfo` instance.
-
-        *interval_multiples* is a boolean that indicates whether ticks
-        should be chosen to be multiple of the interval. This will lock
-        ticks to 'nicer' locations. For example, this will force the
-        ticks to be at hours 0, 6, 12, 18 when hourly ticking is done at
-        6 hour intervals.
-
-        The AutoDateLocator has an interval dictionary that maps the
-        frequency of the tick (a constant from dateutil.rrule) and a
-        multiple allowed for that ticking.  The default looks like this::
-
-          self.intervald = {
-            YEARLY  : [1, 2, 4, 5, 10, 20, 40, 50, 100, 200, 400, 500,
-                      1000, 2000, 4000, 5000, 10000],
-            MONTHLY : [1, 2, 3, 4, 6],
-            DAILY   : [1, 2, 3, 7, 14],
-            HOURLY  : [1, 2, 3, 4, 6, 12],
-            MINUTELY: [1, 5, 10, 15, 30],
-            SECONDLY: [1, 5, 10, 15, 30],
-            MICROSECONDLY: [1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000,
-                           5000, 10000, 20000, 50000, 100000, 200000, 500000,
-                           1000000],
+    Attributes
+    ----------
+    intervald : dict
+
+        Mapping of tick frequencies (a constant from dateutil.rrule) to
+        multiples allowed for that ticking.  The default looks like this::
+
+            self.intervald = {
+                YEARLY  : [1, 2, 4, 5, 10, 20, 40, 50, 100, 200, 400, 500,
+                           1000, 2000, 4000, 5000, 10000],
+                MONTHLY : [1, 2, 3, 4, 6],
+                DAILY   : [1, 2, 3, 7, 14],
+                HOURLY  : [1, 2, 3, 4, 6, 12],
+                MINUTELY: [1, 5, 10, 15, 30],
+                SECONDLY: [1, 5, 10, 15, 30],
+                MICROSECONDLY: [1, 2, 5, 10, 20, 50, 100, 200, 500,
+                                1000, 2000, 5000, 10000, 20000, 50000,
+                                100000, 200000, 500000, 1000000],
             }
 
         The interval is used to specify multiples that are appropriate for
         the frequency of ticking. For instance, every 7 days is sensible
         for daily ticks, but for minutes/seconds, 15 or 30 make sense.
         You can customize this dictionary by doing::
 
-          locator = AutoDateLocator()
-          locator.intervald[HOURLY] = [3] # only show every 3 hours
+            locator = AutoDateLocator()
+            locator.intervald[HOURLY] = [3]  # only show every 3 hours
+    """
+
+    def __init__(self, tz=None, minticks=5, maxticks=None,
+                 interval_multiples=True):
+        """
+        Parameters
+        ----------
+        tz : `tzinfo`
+            Ticks timezone.
+        minticks : int
+            The minimum number of ticks desired; controls whether ticks occur
+            yearly, monthly, etc.
+        maxticks : int
+            The maximum number of ticks desired; controls the interval between
+            ticks (ticking every other, every 3, etc.).  For fine-grained
+            control, this can be a dictionary mapping individual rrule
+            frequency constants (YEARLY, MONTHLY, etc.) to their own maximum
+            number of ticks.  This can be used to keep the number of ticks
+            appropriate to the format chosen in `AutoDateFormatter`. Any
+            frequency not specified in this dictionary is given a default
+            value.
+        interval_multiples : bool, default: True
+            Whether ticks should be chosen to be multiple of the interval,
+            locking them to 'nicer' locations.  For example, this will force
+            the ticks to be at hours 0, 6, 12, 18 when hourly ticking is done
+            at 6 hour intervals.
         """
         DateLocator.__init__(self, tz)
         self._locator = YearLocator(tz=tz)
@@ -1883,17 +1886,16 @@ def weeks(w):
 
 class DateConverter(units.ConversionInterface):
     """
-    Converter for datetime.date and datetime.datetime data,
-    or for date/time data represented as it would be converted
-    by :func:`date2num`.
+    Converter for `datetime.date` and `datetime.datetime` data, or for
+    date/time data represented as it would be converted by `date2num`.
 
     The 'unit' tag for such data is None or a tzinfo instance.
     """
 
     @staticmethod
     def axisinfo(unit, axis):
         """
-        Return the :class:`~matplotlib.units.AxisInfo` for *unit*.
+        Return the `~matplotlib.units.AxisInfo` for *unit*.
 
         *unit* is a tzinfo instance or None.
         The *axis* argument is required but not used.
@@ -1911,8 +1913,8 @@ def axisinfo(unit, axis):
     @staticmethod
     def convert(value, unit, axis):
         """
-        If *value* is not already a number or sequence of numbers,
-        convert it with :func:`date2num`.
+        If *value* is not already a number or sequence of numbers, convert it
+        with `date2num`.
 
         The *unit* and *axis* arguments are not used.
         """
@@ -1939,13 +1941,7 @@ def default_units(x, axis):
 
 
 class ConciseDateConverter(DateConverter):
-    """
-    Converter for datetime.date and datetime.datetime data,
-    or for date/time data represented as it would be converted
-    by :func:`date2num`.
-
-    The 'unit' tag for such data is None or a tzinfo instance.
-    """
+    # docstring inherited
 
     def __init__(self, formats=None, zero_formats=None, offset_formats=None,
                  show_offset=True):
@@ -1956,22 +1952,15 @@ def __init__(self, formats=None, zero_formats=None, offset_formats=None,
         super().__init__()
 
     def axisinfo(self, unit, axis):
-        """
-        Return the :class:`~matplotlib.units.AxisInfo` for *unit*.
-
-        *unit* is a tzinfo instance or None.
-        The *axis* argument is required but not used.
-        """
+        # docstring inherited
         tz = unit
-
         majloc = AutoDateLocator(tz=tz)
         majfmt = ConciseDateFormatter(majloc, tz=tz, formats=self._formats,
                                       zero_formats=self._zero_formats,
                                       offset_formats=self._offset_formats,
                                       show_offset=self._show_offset)
         datemin = datetime.date(2000, 1, 1)
         datemax = datetime.date(2010, 1, 1)
-
         return units.AxisInfo(majloc=majloc, majfmt=majfmt, label='',
                               default_limits=(datemin, datemax))
 
