DOC: Updated docstring DatetimeIndex.tz_localize

pandas/core/indexes/datetimes.py

@@ -1937,16 +1937,22 @@ def tz_convert(self, tz):
                      mapping={True: 'infer', False: 'raise'})
     def tz_localize(self, tz, ambiguous='raise', errors='raise'):
         """
-        Localize tz-naive DatetimeIndex to given time zone (using
-        pytz/dateutil), or remove timezone from tz-aware DatetimeIndex
+        Localize tz-naive DatetimeIndex to tz-aware DatetimeIndex.
+
+        This method takes a naive DatetimeIndex object and make this
+        time zone aware. It does not move the time to another
+        timezone.
+        Time zone localization helps to switch b/w time zone aware and time
+        zone unaware objects.
 
         Parameters
         ----------
         tz : string, pytz.timezone, dateutil.tz.tzfile or None
             Time zone for time. Corresponding timestamps would be converted to
             time zone of the TimeSeries.
             None will remove timezone holding local time.
-        ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise'
+        ambiguous : str {'infer', 'NaT', 'raise'} or bool array, \
+        default 'raise'
             - 'infer' will attempt to infer fall dst-transition hours based on
               order
             - bool-ndarray where True signifies a DST time, False signifies a
@@ -1955,7 +1961,7 @@ def tz_localize(self, tz, ambiguous='raise', errors='raise'):
             - 'NaT' will return NaT where there are ambiguous times
             - 'raise' will raise an AmbiguousTimeError if there are ambiguous
               times
-        errors : 'raise', 'coerce', default 'raise'
+        errors : {'raise', 'coerce'}, default 'raise'
             - 'raise' will raise a NonExistentTimeError if a timestamp is not
                valid in the specified timezone (e.g. due to a transition from
                or to DST time)
@@ -1968,9 +1974,33 @@ def tz_localize(self, tz, ambiguous='raise', errors='raise'):
             .. deprecated:: 0.15.0
                Attempt to infer fall dst-transition hours based on order
 
+
         Returns
         -------
-        localized : DatetimeIndex
+        DatetimeIndex
+            Index converted to the specified time zone.
+
+        Examples
+        --------
+        >>> tz_naive = pd.date_range('2018-03-01', '2018-03-03')
+        >>> tz_naive
+        DatetimeIndex(['2018-03-01', '2018-03-02', '2018-03-03'],
+        dtype='datetime64[ns]', freq='D')
+
+        Localize DatetimeIndex in US/Eastern time zone.
+
+        >>> tz_aware = tz_naive.tz_localize(tz='US/Eastern')
+        >>> tz_aware
+        DatetimeIndex(['2018-03-01 00:00:00-05:00',
+        '2018-03-02 00:00:00-05:00', '2018-03-03 00:00:00-05:00'],
+        dtype='datetime64[ns, US/Eastern]', freq='D')
+
+        Localize time zone aware into naive time zone.
+
+        >>> tz_aware.tz_localize(None)
+        DatetimeIndex(['2018-03-01', '2018-03-02', '2018-03-03'],
+        dtype='datetime64[ns]', freq='D')
+
 
         Raises
         ------