DOC: update pandas.DatetimeIndex.to_period docstring(Nairobi)
Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [ x] PR title is "DOC: update the pandas.DatetimeIndex.to_period docstring"
- [ x] The validation script passes: `scripts/validate_docstrings.py pandas.DatetimeIndex.to_period `
- [ 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 pandas.DatetimeIndex.to_period `
- [ x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```

################################################################################
################## Docstring (pandas.DatetimeIndex.to_period) ##################
################################################################################

Cast to PeriodIndex at a particular frequency.

Converts DatetimeIndex to PeriodIndex.

Parameters
----------
freq : string or pandas offset object, optional
    One of pandas date offset string or corresponding objects.

Returns
-------
period : DatetimeIndex

Examples
--------
>>> df = pd.DataFrame({"y": [1,2,3]},
...                   index=pd.to_datetime(["2000-03-31 00:00:00",
...                                         "2000-05-31 00:00:00",
...                                         "2000-08-31 00:00:00"]))
>>> df.index = df.index.to_period("M")
>>> df
            y
2000-03 1
2000-05 2
2000-08 3

See also
--------
pandas.PeriodIndex: Immutable ndarray holding ordinal values
pandas.DatetimeIndex.to_pydatetime: Return DatetimeIndex as object

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DatetimeIndex.to_period" 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.



