DOC: Update the DatetimeIndex.floor docstring
State: closed

Signed-off-by: Tushar Mittal <chiragmittal.mittal@gmail.com>

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:

```
################################################################################
#################### Docstring (pandas.DatetimeIndex.floor) ####################
################################################################################

Floor the DatetimeIndex to the specified frequency.

Links to the available `frequency strings <http://pandas.
pydata.org/pandas-docs/stable/timeseries.html#offset-aliases>`_
and `frequency objects <http://pandas.pydata.org/pandas-docs/
stable/timeseries.html#dateoffset-objects>`_ .

Parameters
----------
freq : str, object
    String or object specifying the frequency to round down to.

Returns
-------
DatetimeIndex

See Also
--------
DatetimeIndex.ceil : Ceil the DatetimeIndex to the specified freq.
DatetimeIndex.round : Round the DatetimeIndex to the specified freq.

Examples
--------
>>> df = pd.DatetimeIndex(start='2014-08-01 09:23:41.321211',
...                       freq = 'H', periods = 3)
>>> df
DatetimeIndex(['2014-08-01 09:23:41.321211',
               '2014-08-01 10:23:41.321211',
               '2014-08-01 11:23:41.321211'],
                dtype='datetime64[ns]', freq='H')
>>> df.floor('H')
DatetimeIndex(['2014-08-01 09:00:00',
               '2014-08-01 10:00:00',
               '2014-08-01 11:00:00'],
                dtype='datetime64[ns]', freq=None)
>>> df.floor('D')
DatetimeIndex(['2014-08-01', '2014-08-01', '2014-08-01'],
               dtype='datetime64[ns]', freq=None)
>>> df.floor('min')
DatetimeIndex(['2014-08-01 09:23:00',
               '2014-08-01 10:23:00',
               '2014-08-01 11:23:00'],
               dtype='datetime64[ns]', freq=None)

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DatetimeIndex.floor" 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

Comments:
IMHO, since there was a common docstring for `ceil`, `floor`, and `round`, it was quite difficult to make it descriptive (like the see also and examples section) so i had to separate out the docstring for `floor`, same can be done for `ceil` and `round`. :slightly_smiling_face: 
Hello @techytushar! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on March 10, 2018 at 16:50 Hours UTC
@kynan thank you for the review, i have made the required changes. :slightly_smiling_face: 
@jreback please review! :slightly_smiling_face: 
@pandas-dev/pandas-core needs a rebase
@jreback : Do we need this PR anymore?

https://pandas-docs.github.io/pandas-docs-travis/generated/pandas.DatetimeIndex.floor.html
yeah the floor docs are now in pandas/core/indexes/datetimelike.py. let's close but if you think should add to those examples, pls do a PR (or pls create a new issue for that).