DOC: update the pandas.Series.dt.is_year_start docstring

[janelle]

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• 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

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

################################################################################
################## Docstring (pandas.Series.dt.is_year_start) ##################
################################################################################

Return a boolean indicating whether the date is the first day of the
year.

Returns
-------
is_year_start : Series of boolean.

See Also
--------
is_year_end : Return a boolean indicating whether the date is the
    last day of the year.

Examples
--------
>>> dates = pd.Series(pd.date_range("2017-12-30", periods=3))
>>> dates
0   2017-12-30
1   2017-12-31
2   2018-01-01
dtype: datetime64[ns]
>>> dates.dt.is_year_start
0    False
1    False
2    True
dtype: bool

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

Errors found:
    No summary found (a short summary in a single line should be present at the beginning of the docstring)

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.

• short summary exceeds one line by one word, hope that is ok

[TomAugspurger]

Same thing about the single line.

[jorisvandenbossche]

General question here: for attributes, do we want to follow our rule of starting the summary line with a verb?

I have the feeling that if all those attributes start with "Return", that's rather superfluous

[jorisvandenbossche]

For example, this gives now a nice overview table with short explanations: http://pandas.pydata.org/pandas-docs/stable/api.html#time-date-components

Personally, I would say that if all those "The year of the datetime" become "Return the year of the datetime" etc, this is not necessarily an improvement

cc @datapythonista your view here is very appreciated

[datapythonista]

I agree, I think that policy only makes sense to functions and methods, not to classes, properties or attributes.

If I'm not wrong, that is said in the documentation, and also the validation avoids the check for the infinitive verb.

[TomAugspurger]

is_year_end : Series or DatetimeIndex
    The same type as the original data. Series will have the same
    name and index. DatetimeIndex will have the same name.

[TomAugspurger]

Second example showing DatetimeIndex.is_year_start.

[jorisvandenbossche]

Can you then also write something like "This attribute is both available on a DatetimeIndex as a Series with datetime values" or for the Series example: "On a Series with datetime values, the attribute can be accessed with .dt"

[TomAugspurger]

I'm not sure this will resolve correctly, @jorisvandenbossche do you know?

I think it should be Series.dt.is_year_start

or DatetimeIndex.is_year_start. Don't think we've decided what to do here...

[jorisvandenbossche]

Well, I was just testing it :-)
Turns out this works (because it is the same class, it resolves OK), but I wanted to comment that for clarity I would write it in full like DatetimeIndex.is_year_start, but on the other hand, not writing it full ensures it links correctly in both Series.dt and DatetimeIndex case

[TomAugspurger]

Ah, in that case I'm ok with leaving it "ambiguous" since in the HTML docs you can click through and get the correct one. In the REPL you have tab completion.

[jreback]

blank line between cases

[TomAugspurger]

And thanks again :)