Add tabular string of offset aliases for docstring appending

Table is derived from first lines of docstrings; all classes
in `_all__` had docstrings revised.

Author: patricktokeeffe

pandas/tseries/offsets.py

@@ -292,9 +292,7 @@ def _from_name(cls, suffix=None):
 
 
 class BusinessDay(CacheableOffset, SingleConstructorOffset):
-    """
-    DateOffset subclass representing possibly n business days
-    """
+    """Business day (weekday)"""
     _prefix = 'B'
 
     def __init__(self, n=1, **kwds):
@@ -425,7 +423,8 @@ def onOffset(cls, dt):
 
 
 class CustomBusinessDay(BusinessDay):
-    """
+    """Custom representation **EXPERIMENTAL**
+
     **EXPERIMENTAL** DateOffset subclass representing possibly n business days
     excluding holidays
 
@@ -445,6 +444,7 @@ class CustomBusinessDay(BusinessDay):
     holidays : list
         list/array of dates to exclude from the set of valid business days,
         passed to ``numpy.busdaycalendar``
+
     """
 
     _cacheable = False
@@ -547,7 +547,7 @@ def name(self):
 
 
 class MonthEnd(CacheableOffset, MonthOffset):
-    """DateOffset of one month end"""
+    """Calendar month end date"""
 
     def apply(self, other):
         other = datetime(other.year, other.month, other.day,
@@ -571,7 +571,7 @@ def onOffset(cls, dt):
 
 
 class MonthBegin(CacheableOffset, MonthOffset):
-    """DateOffset of one month at beginning"""
+    """Calendar month begin date"""
 
     def apply(self, other):
         n = self.n
@@ -590,7 +590,7 @@ def onOffset(cls, dt):
 
 
 class BusinessMonthEnd(CacheableOffset, MonthOffset):
-    """DateOffset increments between business EOM dates"""
+    """Business month end dates"""
 
     def isAnchored(self):
         return (self.n == 1)
@@ -618,7 +618,7 @@ def apply(self, other):
 
 
 class BusinessMonthBegin(CacheableOffset, MonthOffset):
-    """DateOffset of one business month at beginning"""
+    """Business month begin date"""
 
     def apply(self, other):
         n = self.n
@@ -653,13 +653,13 @@ def onOffset(cls, dt):
 
 
 class Week(CacheableOffset, DateOffset):
-    """
-    Weekly offset
+    """Week, optionally anchored on day of the week
 
     Parameters
     ----------
     weekday : int, default None
         Always generate specific day of week. 0 for Monday
+
     """
 
     def __init__(self, n=1, **kwds):
@@ -720,6 +720,7 @@ def _from_name(cls, suffix=None):
             weekday = _weekday_to_int[suffix]
         return cls(weekday=weekday)
 
+
 class WeekDay(object):
     MON = 0
     TUE = 1
@@ -743,8 +744,7 @@ class WeekDay(object):
 
 
 class WeekOfMonth(CacheableOffset, DateOffset):
-    """
-    Describes monthly dates like "the Tuesday of the 2nd week of each month"
+    """Dates like "Tuesday of the 2nd week each month"
 
     Parameters
     ----------
@@ -759,6 +759,7 @@ class WeekOfMonth(CacheableOffset, DateOffset):
         4: Fridays
         5: Saturdays
         6: Sundays
+
     """
 
     def __init__(self, n=1, **kwds):
@@ -828,9 +829,9 @@ def _from_name(cls, suffix=None):
         weekday = _weekday_to_int[suffix[1:]]
         return cls(week=week, weekday=weekday)
 
+
 class LastWeekOfMonth(CacheableOffset, DateOffset):
-    """
-    Describes monthly dates in last week of month like "the last Tuesday of each month"
+    """Dates like "last Tuesday of the month"
 
     Parameters
     ----------
@@ -843,7 +844,9 @@ class LastWeekOfMonth(CacheableOffset, DateOffset):
         4: Fridays
         5: Saturdays
         6: Sundays
+
     """
+
     def __init__(self, n=1, **kwds):
         self.n = n
         self.weekday = kwds['weekday']
@@ -939,10 +942,12 @@ def rule_code(self):
 
 
 class BQuarterEnd(CacheableOffset, QuarterOffset):
-    """DateOffset increments between business Quarter dates
+    """Business quarter end date
+
     startingMonth = 1 corresponds to dates like 1/31/2007, 4/30/2007, ...
     startingMonth = 2 corresponds to dates like 2/28/2007, 5/31/2007, ...
     startingMonth = 3 corresponds to dates like 3/30/2007, 6/29/2007, ...
+
     """
     _outputName = 'BusinessQuarterEnd'
     _default_startingMonth = 3
@@ -977,9 +982,9 @@ def onOffset(self, dt):
         modMonth = (dt.month - self.startingMonth) % 3
         return BMonthEnd().onOffset(dt) and modMonth == 0
 
+
 class FY5253(CacheableOffset, DateOffset):
-    """
-    Describes 52-53 week fiscal year. This is also known as a 4-4-5 calendar.
+    """End date, 52-53 week fiscal year (4-4-5 calendar)
 
     It is used by companies that desire that their
     fiscal year always end on the same day of the week.
@@ -1013,6 +1018,7 @@ class FY5253(CacheableOffset, DateOffset):
     startingMonth : The month in which fiscal years end. {1, 2, ... 12}
     variation : str
         {"nearest", "last"} for "LastOfMonth" or "NearestEndMonth"
+
     """
 
     _prefix = 'RE'
@@ -1142,13 +1148,12 @@ def _parse_suffix(cls, varion_code, startingMonth_code, weekday_code):
     def _from_name(cls, *args):
         return cls(**cls._parse_suffix(*args))
 
+
 class FY5253Quarter(CacheableOffset, DateOffset):
-    """
-    DateOffset increments between business quarter dates
-    for 52-53 week fiscal year (also known as a 4-4-5 calendar).
+    """Quarter end, 52-53 week fiscal year (4-4-5 calendar)
 
-    It is used by companies that desire that their
-    fiscal year always end on the same day of the week.
+    The 4-4-5 calendar is used by companies that desire that
+    their fiscal year always end on the same day of the week.
 
     It is a method of managing accounting periods.
     It is a common calendar structure for some industries,
@@ -1184,6 +1189,7 @@ class FY5253Quarter(CacheableOffset, DateOffset):
         or 14 week when needed. {1,2,3,4}
     variation : str
         {"nearest", "last"} for "LastOfMonth" or "NearestEndMonth"
+
     """
 
     _prefix = 'REQ'
@@ -1311,6 +1317,8 @@ def _from_name(cls, *args):
 
 # TODO: This is basically the same as BQuarterEnd
 class BQuarterBegin(CacheableOffset, QuarterOffset):
+    """Business quarter begin date"""
+
     _outputName = "BusinessQuarterBegin"
     # I suspect this is wrong for *all* of them.
     _default_startingMonth = 3
@@ -1348,7 +1356,8 @@ def apply(self, other):
 
 
 class QuarterEnd(CacheableOffset, QuarterOffset):
-    """DateOffset increments between business Quarter dates
+    """Calendar quarter end date
+
     startingMonth = 1 corresponds to dates like 1/31/2007, 4/30/2007, ...
     startingMonth = 2 corresponds to dates like 2/28/2007, 5/31/2007, ...
     startingMonth = 3 corresponds to dates like 3/31/2007, 6/30/2007, ...
@@ -1389,6 +1398,8 @@ def onOffset(self, dt):
 
 
 class QuarterBegin(CacheableOffset, QuarterOffset):
+    """Calendar quarter begin date"""
+
     _outputName = 'QuarterBegin'
     _default_startingMonth = 3
     _from_name_startingMonth = 1
@@ -1441,7 +1452,8 @@ def rule_code(self):
 
 
 class BYearEnd(CacheableOffset, YearOffset):
-    """DateOffset increments between business EOM dates"""
+    """Business year end date"""
+
     _outputName = 'BusinessYearEnd'
     _default_month = 12
     _prefix = 'BA'
@@ -1478,7 +1490,8 @@ def apply(self, other):
 
 
 class BYearBegin(CacheableOffset, YearOffset):
-    """DateOffset increments between business year begin dates"""
+    """Business year begin date"""
+
     _outputName = 'BusinessYearBegin'
     _default_month = 1
     _prefix = 'BAS'
@@ -1510,7 +1523,8 @@ def apply(self, other):
 
 
 class YearEnd(CacheableOffset, YearOffset):
-    """DateOffset increments between calendar year ends"""
+    """Calendar year end date"""
+
     _default_month = 12
     _prefix = 'A'
 
@@ -1566,7 +1580,8 @@ def onOffset(self, dt):
 
 
 class YearBegin(CacheableOffset, YearOffset):
-    """DateOffset increments between calendar year begin dates"""
+    """Calendar year begin date"""
+
     _default_month = 1
     _prefix = 'AS'
 
@@ -1731,35 +1746,42 @@ def _delta_to_nanoseconds(delta):
 
 
 class Day(CacheableOffset, Tick):
+    """One calendar day"""
     _inc = timedelta(1)
     _prefix = 'D'
 
 
 class Hour(Tick):
+    """One hour"""
     _inc = timedelta(0, 3600)
     _prefix = 'H'
 
 
 class Minute(Tick):
+    """One minute"""
     _inc = timedelta(0, 60)
     _prefix = 'T'
-
+    
 
 class Second(Tick):
+    """One second"""
     _inc = timedelta(0, 1)
     _prefix = 'S'
 
 
 class Milli(Tick):
+    """One millisecond"""
     _prefix = 'L'
 
 
 class Micro(Tick):
+    """One microsecond"""
     _inc = timedelta(microseconds=1)
     _prefix = 'U'
 
 
 class Nano(Tick):
+    """One nanosecond"""
     _inc = np.timedelta64(1, 'ns') if not _np_version_under1p7 else 1
     _prefix = 'N'
 
@@ -1796,6 +1818,7 @@ def generate_range(start=None, end=None, periods=None,
     start : datetime (default None)
     end : datetime (default None)
     periods : int, optional
+    offset : DateOffset, default BusinessDay
     time_rule : (legacy) name of DateOffset object to be used, optional
         Corresponds with names expected by tseries.frequencies.get_offset
 
@@ -1875,6 +1898,11 @@ def generate_range(start=None, end=None, periods=None,
     FY5253Quarter,
 ])
 
+_alias_doc = 'Offset Aliases\n--------------\n' + \
+    '\n'.join(sorted([item.ljust(max([len(s) for s in __all__])+2) + \
+    (locals()[item].__doc__.split('\n')[0].strip() or '<no docstring found>') \
+    for item in __all__]))
+
 if not _np_version_under1p7:
     # Only 1.7+ supports nanosecond resolution
     prefix_mapping['N'] = Nano