DOC: update the Period.days_in_month docstring

[Tushar987]

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

################################################################################
################### Docstring (pandas.Period.days_in_month)  ###################
################################################################################

Get the total number of days in the month that this period falls on.

Returns
-------
int

See Also
--------
Period.daysinmonth : Returns the number of days in the month.
DatetimeIndex.daysinmonth : Return the number of days in the month.
calendar.monthrange : Return a tuple containing weekday
    (0-6 ~ Mon-Sun) and number of days (28-31).

Examples
--------
>>> p= pd.Period('2018-2-17')
>>> p.days_in_month
28

>>> import datetime
>>> pd.Period(datetime.datetime.today(), freq= 'B').days_in_month
31

Handles the leap year case as well:

>>> p= pd.Period('2016-2-17')
>>> p.days_in_month
29

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

Errors found:
	No extended summary found

• Short summary summarises pretty much all the characteristics of this attribute.

[IHackPy]

In See Also section : place of Returns use Get

[IHackPy]

apart from this LGTM

[Tushar987]

Sure! I will make the suggested changes. Thanks for the review.

[TomAugspurger]

Can you avoid datetime.today()? This won't pass doctests, aside from ~half the months in the year :)

[Tushar987]

yeah sure !! Please pardon my naivety and this is a lifetime learning for sure. :)

[Tushar987]

Should I just remove the second example because I couldn't think of any other way around of using this attribute different than the first example?

[TomAugspurger]

Using Period('2018-03-01').days_in_month should be fine.

[TomAugspurger]

Returns -> Return

[TomAugspurger]

Using Period('2018-03-01').days_in_month should be fine.

[TomAugspurger]

pep8: space before the =

[TomAugspurger]

space before the =

[Tushar987]

@himanshuawasthi95 @TomAugspurger, Made the suggested changes. Please Review.

[TomAugspurger]

@Tushar987 Did you push your changes with the PEP8 fixes (the spaces before the =, so p = ...)?

[TomAugspurger]

Oh, also the datetime.today change. I'm guessing you just need to push :)

[Tushar987]

@TomAugspurger, Sorry! forgot to push changes. Please review.

[TomAugspurger]

Looks good, thanks!

[jorisvandenbossche]

Hmm, I also recently merged PR for daysinmonth: #20295
Probably we should try to consolidate both (and let them have a shared docstring)