DOC: update the pandas.DatetimeIndex docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [ ] PR title is "DOC: update the pandas.DatetimeIndex docstring"
- [ ] The validation script passes: `scripts/validate_docstrings.py pandas.DatetimeIndex`
- [ ] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] The html version looks good: `python doc/make.py --single pandas.DatetimeIndex`
- [ ] 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) #######################
################################################################################

Store Datetime index using NumPy's datetime64 dtype.

Immutable ndarray of datetime64 data, represented internally as int64, and
which can be boxed to Timestamp objects that are subclasses of datetime and
carry metadata such as frequency information.

Parameters
----------
data : array-like (1-dimensional), optional
    Optional datetime-like data to construct index with.
freq : str or pandas offset object, optional
    One of pandas date offset strings or corresponding objects.
start : datetime-like, optional
    Shapes the starting value and if data is None,
    start is used as the start point in generating regular timestamp data.
end : datetime-like, optional
    Shapes the end time, if periods is none, generated index will extend
    to first conforming time on or just past end argument.
copy : bool
    Make a copy of input ndarray.
name : object
    Name to be stored in the index.
tz : pytz.timezone or dateutil.tz.tzfile.
verify_integrity : bool, default False
    Check new index for duplicates, otherwise defer until necessary.
normalize : bool
    Return DatetimeIndex with times to midnight.
closed : str or None, default None
    Make the interval closed with respect to the given frequency to
    the 'left', 'right', or both sides (None).
ambiguous : 'infer', bool-ndarray, 'NaT', 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
      non-DST time (note that this flag is only applicable for ambiguous
      times).
    - 'NaT' will return NaT where there are ambiguous times.
    - 'raise' will raise an AmbiguousTimeError if there are ambiguous times
dtype : object
    Specify the datatype to DataFrame constructor.
**kwargs
    For compatibility. Has no effect on the result.

Attributes
----------
year
month
day
hour
minute
second
microsecond
nanosecond
date
time
dayofyear
weekofyear
week
dayofweek
weekday
quarter
tz
freq
freqstr
is_month_start
is_month_end
is_quarter_start
is_quarter_end
is_year_start
is_year_end
is_leap_year
inferred_freq

Methods
-------
normalize
strftime
snap
tz_convert
tz_localize
round
floor
ceil
to_period
to_perioddelta
to_pydatetime
to_series
to_frame
month_name
day_name

Notes
-----
To learn more about the frequency strings, please see `this link
<http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`__.

See Also
---------
Index : The base pandas Index type
TimedeltaIndex : Index of timedelta64 data
PeriodIndex : Index of Period data

Examples
--------
>>> # Generate a date range with month end frequency
>>> pd.DatetimeIndex(start='2018-3-10', freq='M', periods=4)
DatetimeIndex(['2018-03-31', '2018-04-30',
               '2018-05-31', '2018-06-30'],
              dtype='datetime64[ns]', freq='M')

>>> # Hourly time range with end conforming the period
>>> pd.DatetimeIndex(start='2015-03-01 21:00:00', end='2015-03-02', freq='H')
DatetimeIndex(['2015-03-01 21:00:00', '2015-03-01 22:00:00',
               '2015-03-01 23:00:00', '2015-03-02 00:00:00'],
              dtype='datetime64[ns]', freq='H')

>>> # Generate time range with with 1 minute frequency
>>> pd.date_range('2018-03-10', periods=4, freq='1min')
DatetimeIndex(['2018-03-10 00:00:00', '2018-03-10 00:01:00',
               '2018-03-10 00:02:00', '2018-03-10 00:03:00'],
              dtype='datetime64[ns]', freq='T')

>>> # Weekly date range with closed argument to mark end date interval
>>> pd.date_range('2018-03-10', '2018-03-31', freq='W', closed='right')
DatetimeIndex(['2018-03-11', '2018-03-18', '2018-03-25'],
              dtype='datetime64[ns]', freq='W-SUN')

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'periods', 'kwargs'} not documented
		Unknown parameters {'**kwargs'}
```

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

Comments:
Hello @4bic! Thanks for updating the PR.

 - In the file [`pandas/core/indexes/datetimes.py`](https://github.com/pandas-dev/pandas/blob/4da8cfc5fa53dd3e318f4dad8e54e2d614b4e202/pandas/core/indexes/datetimes.py), following are the PEP8 issues :

> [Line 289:80](https://github.com/pandas-dev/pandas/blob/4da8cfc5fa53dd3e318f4dad8e54e2d614b4e202/pandas/core/indexes/datetimes.py#L289): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (81 > 79 characters)



##### Comment last updated on March 26, 2018 at 14:43 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20465?src=pr&el=h1) Report
> Merging [#20465](https://codecov.io/gh/pandas-dev/pandas/pull/20465?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/c9e8f59668b63738cccb913f837c529887097da1?src=pr&el=desc) will **increase** coverage by `0.03%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #20465      +/-   ##
==========================================
+ Coverage   91.81%   91.85%   +0.03%     
==========================================
  Files         152      152              
  Lines       49261    49235      -26     
==========================================
- Hits        45231    45224       -7     
+ Misses       4030     4011      -19
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.24% <ø> (+0.03%)` | :arrow_up: |
| #single | `41.88% <ø> (-0.02%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20465?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.74% <ø> (ø)` | :arrow_up: |
| [pandas/io/formats/terminal.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvdGVybWluYWwucHk=) | `16.43% <0%> (-4.55%)` | :arrow_down: |
| [pandas/core/arrays/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2Jhc2UucHk=) | `83.33% <0%> (-0.82%)` | :arrow_down: |
| [pandas/core/algorithms.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYWxnb3JpdGhtcy5weQ==) | `94.29% <0%> (-0.07%)` | :arrow_down: |
| [pandas/core/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYmFzZS5weQ==) | `96.78% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.84% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/panel.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcGFuZWwucHk=) | `97.29% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.18% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/dtypes/missing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL21pc3NpbmcucHk=) | `91.07% <0%> (ø)` | :arrow_up: |
| [pandas/io/formats/format.py](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvZm9ybWF0LnB5) | `98.24% <0%> (ø)` | :arrow_up: |
| ... and [8 more](https://codecov.io/gh/pandas-dev/pandas/pull/20465/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20465?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/20465?src=pr&el=footer). Last update [c9e8f59...0636fbc](https://codecov.io/gh/pandas-dev/pandas/pull/20465?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

I added a small edit (added back the periods keyword explanation), and fixed the conflict with master (in the meantime, there had been done some changes to that docstring)
can you rebase and update for comments
closing as stale. if you'd like to continue pls ping.