DOC: update the pandas.Series.shift docstring

Author: Yitzhak Andrade

pandas/core/generic.py

@@ -7606,28 +7606,31 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
         Shift index by desired number of periods with an optional time `freq`.
 
         When `freq` is not passed, shift the index without realigning the data.
-        If `freq` is passed (in this case, the index must be date or datetime),
-        the index will be increased using the periods and the `freq`.
+        If `freq` is passed (in this case, the index must be date or datetime,
+        or it will raises a `NotImplementedError`), the index will be
+        increased using the periods and the `freq`.
 
         Parameters
         ----------
         periods : int
             Number of periods to shift; can be positive or negative.
         freq : DateOffset, timedelta, or time rule string, optional
             Increment to use from the tseries module or time rule (e.g. 'EOM').
-            See Notes.
+            If `freq` is specified then the index values are shifted but the
+            data is not realigned. That is, use `freq` if you would like to
+            extend the index when shifting and preserve the original data.
         axis : {0 or ‘index’, 1 or ‘columns’, None}, default None
             Shift direction.
 
-        Notes
-        -----
-        If `freq` is specified then the index values are shifted but the data
-        is not realigned. That is, use `freq` if you would like to extend the
-        index when shifting and preserve the original data.
-
         Returns
         -------
-        shifted : %(klass)s
+        %(klass)s
+            Copy of input object, shifted.
+
+        See Also
+        --------
+        tshift : Shift the time index, using the index’s frequency if
+            available.
 
         Examples
         --------
@@ -7651,42 +7654,42 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
         3   NaN  30.0  33.0
         4   NaN  45.0  48.0
 
-        >>> import datetime
-        >>> names = ['João', 'Maria', 'Emanuel', 'Jussara', 'José']
-        >>> dates = [datetime.datetime(2018, 3, 1, 11, 15),
-        ...          datetime.datetime(2018, 3, 5, 11, 15),
-        ...          datetime.datetime(2018, 3, 10, 11, 15),
-        ...          datetime.datetime(2018, 3, 15, 11, 15),
-        ...          datetime.datetime(2018, 3, 20, 11, 15)]
+        **freq parameter**
+
+        When using the freq parameter with a :class:pandas.DateTimeIndex
+        the index values are shifted but the data is not realigned.
+
+        >>> names = ['Joaquim', 'Maria', 'Emanuel', 'Jussara', 'Geraldo']
+        >>> dates = pd.date_range(start='2018-03-05 11:15:00',
+        ...                       freq='5D', periods=5)
         >>> df = pd.DataFrame(data={'names': names}, index=dates)
         >>> df
                                names
-        2018-03-01 11:15:00     João
-        2018-03-05 11:15:00    Maria
-        2018-03-10 11:15:00  Emanuel
-        2018-03-15 11:15:00  Jussara
-        2018-03-20 11:15:00     José
+        2018-03-05 11:15:00  Joaquim
+        2018-03-10 11:15:00    Maria
+        2018-03-15 11:15:00  Emanuel
+        2018-03-20 11:15:00  Jussara
+        2018-03-25 11:15:00  Geraldo
+
+        Shift the index by 2 days (offset-alias 'D').
 
         >>> df.shift(periods=2, freq='D')
                                names
-        2018-03-03 11:15:00     João
-        2018-03-07 11:15:00    Maria
-        2018-03-12 11:15:00  Emanuel
-        2018-03-17 11:15:00  Jussara
-        2018-03-22 11:15:00     José
+        2018-03-07 11:15:00  Joaquim
+        2018-03-12 11:15:00    Maria
+        2018-03-17 11:15:00  Emanuel
+        2018-03-22 11:15:00  Jussara
+        2018-03-27 11:15:00  Geraldo
+
+        Shift the index by 75 minutes (offset-alias 'min').
 
         >>> df.shift(periods=75, freq='min')
                                names
-        2018-03-01 12:30:00     João
-        2018-03-05 12:30:00    Maria
-        2018-03-10 12:30:00  Emanuel
-        2018-03-15 12:30:00  Jussara
-        2018-03-20 12:30:00     José
-
-        See Also
-        --------
-        tshift : Shift the time index, using the index’s frequency if
-            available.
+        2018-03-05 12:30:00  Joaquim
+        2018-03-10 12:30:00    Maria
+        2018-03-15 12:30:00  Emanuel
+        2018-03-20 12:30:00  Jussara
+        2018-03-25 12:30:00  Geraldo
     """)
 
     @Appender(_shared_docs['shift'] % _shared_doc_kwargs)