DOC: update the pandas.Series.shift docstring

Author: Yitzhak Andrade

pandas/core/generic.py

@@ -6815,26 +6815,26 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
                           errors=errors)
 
     _shared_docs['shift'] = ("""
-        Shift index by desired number of periods with an optional time freq.
+        Shift index by desired number of periods with an optional time `freq`.
 
-        When freq is not passed, shift the index without realign 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.
+        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`.
 
         Parameters
         ----------
         periods : int
-            Number of periods to move, can be positive or negative.
+            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.
-        axis : int or str
-            Shift direction. %(axes_single_arg)s.
+        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
+        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
@@ -6843,18 +6843,9 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
 
         Examples
         --------
-        >>> df = pd.DataFrame({'Col1': [10, 20, 30, 20, 15, 30, 45],
-        ...                    'Col2': [13, 23, 33, 23, 18, 33, 48],
-        ...                    'Col3': [17, 27, 37, 27, 22, 37, 52]})
-        >>> print(df)
-           Col1  Col2  Col3
-        0    10    13    17
-        1    20    23    27
-        2    30    33    37
-        3    20    23    27
-        4    15    18    22
-        5    30    33    37
-        6    45    48    52
+        >>> df = pd.DataFrame({'Col1': [10, 20, 15, 30, 45],
+        ...                    'Col2': [13, 23, 18, 33, 48],
+        ...                    'Col3': [17, 27, 22, 37, 52]})
 
         >>> df.shift(periods=3)
            Col1  Col2  Col3
@@ -6863,18 +6854,14 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
         2   NaN   NaN   NaN
         3  10.0  13.0  17.0
         4  20.0  23.0  27.0
-        5  30.0  33.0  37.0
-        6  20.0  23.0  27.0
 
         >>> df.shift(periods=1, axis=1)
            Col1  Col2  Col3
         0   NaN  10.0  13.0
         1   NaN  20.0  23.0
-        2   NaN  30.0  33.0
-        3   NaN  20.0  23.0
-        4   NaN  15.0  18.0
-        5   NaN  30.0  33.0
-        6   NaN  45.0  48.0
+        2   NaN  15.0  18.0
+        3   NaN  30.0  33.0
+        4   NaN  45.0  48.0
 
         >>> import datetime
         >>> names = ['João', 'Maria', 'Emanuel', 'Jussara', 'José']
@@ -6884,7 +6871,7 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
         ...          datetime.datetime(2018, 3, 15, 11, 15),
         ...          datetime.datetime(2018, 3, 20, 11, 15)]
         >>> df = pd.DataFrame(data={'names': names}, index=dates)
-        >>> print(df)
+        >>> df
                                names
         2018-03-01 11:15:00     João
         2018-03-05 11:15:00    Maria
@@ -6910,8 +6897,8 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
 
         See Also
         --------
-        slice_shift: Equivalent to shift without copying data.
-        tshift: Shift the time index, using the index’s frequency if available.
+        tshift : Shift the time index, using the index’s frequency if
+            available.
     """)
 
     @Appender(_shared_docs['shift'] % _shared_doc_kwargs)