DOC: update the DatetimeIndex.tz_convert(tz) docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
(pandas_dev) root@kalih:~/pythonpanda/pandas# python -m flake8 ./pandas/core/indexes/datetimes.py
(pandas_dev) root@kalih:~/pythonpanda/pandas# python scripts/validate_docstrings.py pandas.DatetimeIndex.tz_convert

################################################################################
################# Docstring (pandas.DatetimeIndex.tz_convert)  #################
################################################################################

Convert tz-aware DatetimeIndex from one time zone to another.

When using DatetimeIndex providing with timezone this method
converts tz(timezone)-aware DatetimeIndex from one timezone
to another.

Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
    Time zone for time. Corresponding timestamps would be converted
    to time zone of the DatetimeIndex.
    None will remove timezone holding UTC time.

Returns
-------
normalized : DatetimeIndex

Raises
------
TypeError
    If DatetimeIndex is tz-naive.

See Also
--------
tz_localize : Localize tz-naive DatetimeIndex to given time zone,
              or remove timezone from tz-aware DatetimeIndex.

Examples
--------
With the `tz` parameter, we can change the DatetimeIndex
to other time zones:

>>> dti = pd.DatetimeIndex(start='2014-08-01 09:00',
...                       freq='H', periods=3)

>>> dti
DatetimeIndex(['2014-08-01 09:00:00',
               '2014-08-01 10:00:00',
               '2014-08-01 11:00:00'],
                dtype='datetime64[ns]', freq='H')

>>> dti.tz_localize('Europe/Berlin').tz_convert('US/Eastern')
DatetimeIndex(['2014-08-01 03:00:00-04:00',
               '2014-08-01 04:00:00-04:00',
               '2014-08-01 05:00:00-04:00'],
                dtype='datetime64[ns, US/Eastern]', freq='H')

With the `None` parameter, we can remove the timezone:

>>> dti = pd.DatetimeIndex(start='2014-08-01 09:00',freq='H',
...                        periods=3, tz='Europe/Berlin')

>>> dti
DatetimeIndex(['2014-08-01 09:00:00+02:00',
               '2014-08-01 10:00:00+02:00',
               '2014-08-01 11:00:00+02:00'],
                dtype='datetime64[ns, Europe/Berlin]', freq='H')

>>> dti.tz_convert(None)
DatetimeIndex(['2014-08-01 07:00:00',
               '2014-08-01 08:00:00',
               '2014-08-01 09:00:00'],
                dtype='datetime64[ns]', freq='H')

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DatetimeIndex.tz_convert" correct. :)
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.


Labels:
name: Docs
name: Timezones
description: Timezone data dtype

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20096?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@c748de0`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20096/graphs/tree.svg?height=150&width=650&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/20096?src=pr&el=tree)

```diff
@@            Coverage Diff            @@
##             master   #20096   +/-   ##
=========================================
  Coverage          ?   91.72%           
=========================================
  Files             ?      150           
  Lines             ?    49156           
  Branches          ?        0           
=========================================
  Hits              ?    45090           
  Misses            ?     4066           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.11% <100%> (?)` | |
| #single | `41.85% <100%> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20096?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/20096/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.64% <100%> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20096?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20096?src=pr&el=footer). Last update [c748de0...ff00665](https://codecov.io/gh/pandas-dev/pandas/pull/20096?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

made the required changes, please review @jreback 
Made a few changes. Biggest one being changing the first example to demonstrate `tz_convert` instead of `tz_localize`.
Thanks @hammadmashkoor !