DOC: fix PR02 errors in docstrings

[jordan-d-murphy]

Pandas has a script for validating docstrings:

pandas/ci/code_checks.sh

Lines 72 to 194 in 9008ee5

	MSG='Partially validate docstrings (PR02)' ; echo $MSG
	$BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=PR02 --ignore_functions \
	pandas.io.formats.style.Styler.to_excel\
	pandas.CategoricalIndex.rename_categories\
	pandas.CategoricalIndex.reorder_categories\
	pandas.CategoricalIndex.add_categories\
	pandas.CategoricalIndex.remove_categories\
	pandas.CategoricalIndex.set_categories\
	pandas.IntervalIndex.set_closed\
	pandas.IntervalIndex.contains\
	pandas.IntervalIndex.overlaps\
	pandas.IntervalIndex.to_tuples\
	pandas.DatetimeIndex.round\
	pandas.DatetimeIndex.floor\
	pandas.DatetimeIndex.ceil\
	pandas.DatetimeIndex.month_name\
	pandas.DatetimeIndex.day_name\
	pandas.DatetimeIndex.to_period\
	pandas.DatetimeIndex.std\
	pandas.TimedeltaIndex.round\
	pandas.TimedeltaIndex.floor\
	pandas.TimedeltaIndex.ceil\
	pandas.PeriodIndex\
	pandas.PeriodIndex.strftime\
	pandas.Series.clip\
	pandas.Series.rename_axis\
	pandas.Series.interpolate\
	pandas.Series.dt.to_period\
	pandas.Series.dt.tz_localize\
	pandas.Series.dt.tz_convert\
	pandas.Series.dt.strftime\
	pandas.Series.dt.round\
	pandas.Series.dt.floor\
	pandas.Series.dt.ceil\
	pandas.Series.dt.month_name\
	pandas.Series.dt.day_name\
	pandas.Series.str.wrap\
	pandas.Series.cat.rename_categories\
	pandas.Series.cat.reorder_categories\
	pandas.Series.cat.add_categories\
	pandas.Series.cat.remove_categories\
	pandas.Series.cat.set_categories\
	pandas.Series.plot\
	pandas.Series.plot.bar\
	pandas.Series.plot.barh\
	pandas.Series.plot.line\
	pandas.Series.plot.pie\
	pandas.DataFrame.clip\
	pandas.DataFrame.plot\
	pandas.DataFrame.plot.bar\
	pandas.DataFrame.plot.barh\
	pandas.DataFrame.plot.line\
	pandas.DataFrame.plot.pie\
	pandas.tseries.offsets.DateOffset\
	pandas.tseries.offsets.BusinessDay\
	pandas.tseries.offsets.BDay\
	pandas.tseries.offsets.BusinessHour\
	pandas.tseries.offsets.CustomBusinessDay\
	pandas.tseries.offsets.CDay\
	pandas.tseries.offsets.CustomBusinessHour\
	pandas.tseries.offsets.MonthEnd\
	pandas.tseries.offsets.MonthBegin\
	pandas.tseries.offsets.BusinessMonthEnd\
	pandas.tseries.offsets.BMonthEnd\
	pandas.tseries.offsets.BusinessMonthBegin\
	pandas.tseries.offsets.BMonthBegin\
	pandas.tseries.offsets.CustomBusinessMonthEnd\
	pandas.tseries.offsets.CBMonthEnd\
	pandas.tseries.offsets.CustomBusinessMonthBegin\
	pandas.tseries.offsets.CBMonthBegin\
	pandas.tseries.offsets.SemiMonthEnd\
	pandas.tseries.offsets.SemiMonthBegin\
	pandas.tseries.offsets.Week\
	pandas.tseries.offsets.WeekOfMonth\
	pandas.tseries.offsets.LastWeekOfMonth\
	pandas.tseries.offsets.BQuarterEnd\
	pandas.tseries.offsets.BQuarterBegin\
	pandas.tseries.offsets.QuarterEnd\
	pandas.tseries.offsets.QuarterBegin\
	pandas.tseries.offsets.BYearEnd\
	pandas.tseries.offsets.BYearBegin\
	pandas.tseries.offsets.YearEnd\
	pandas.tseries.offsets.YearBegin\
	pandas.tseries.offsets.FY5253\
	pandas.tseries.offsets.FY5253Quarter\
	pandas.tseries.offsets.Easter\
	pandas.tseries.offsets.Day\
	pandas.tseries.offsets.Hour\
	pandas.tseries.offsets.Minute\
	pandas.tseries.offsets.Second\
	pandas.tseries.offsets.Milli\
	pandas.tseries.offsets.Micro\
	pandas.tseries.offsets.Nano\
	pandas.describe_option\
	pandas.reset_option\
	pandas.get_option\
	pandas.set_option\
	pandas.Timestamp.max\
	pandas.Timestamp.min\
	pandas.Timestamp.resolution\
	pandas.Timedelta.max\
	pandas.Timedelta.min\
	pandas.Timedelta.resolution\
	pandas.Interval\
	pandas.Grouper\
	pandas.core.groupby.SeriesGroupBy.apply\
	pandas.core.groupby.SeriesGroupBy.transform\
	pandas.core.groupby.DataFrameGroupBy.transform\
	pandas.core.groupby.DataFrameGroupBy.nth\
	pandas.core.groupby.DataFrameGroupBy.rolling\
	pandas.core.groupby.SeriesGroupBy.idxmax\
	pandas.core.groupby.SeriesGroupBy.idxmin\
	pandas.core.groupby.SeriesGroupBy.nth\
	pandas.core.groupby.SeriesGroupBy.rolling\
	pandas.core.groupby.DataFrameGroupBy.hist\
	pandas.core.groupby.DataFrameGroupBy.plot\
	pandas.core.groupby.SeriesGroupBy.plot\
	pandas.read_hdf\
	pandas.HDFStore.append\
	pandas.core.window.rolling.Rolling.quantile\
	pandas.core.window.expanding.Expanding.quantile\
	pandas.api.extensions.ExtensionArray.argsort # There should be no backslash in the final line, please keep this comment in the last ignored function
	RET=$(($RET + $?)) ; echo $MSG "DONE"

Currently, some methods fail the PR02 check.

The task here is:

• take 2-4 methods
• run: scripts/validate_docstrings.py --format=actions --errors=PR02 method-name
• check if validation docstrings passes for those methods, and if it’s necessary fix the docstrings according to whatever error is reported
• remove those methods from code_checks.sh
• commit, push, open pull request

Please don't comment take as multiple people can work on this issue. You also don't need to ask for permission to work on this, just comment on which methods are you going to work.

If you're new contributor, please check the contributing guide

thanks @natmokval @mroeschke for the inspiration for this issue

[jordan-d-murphy]

I'll take

• pandas.Series.interpolate
• pandas.read_hdf
• pandas.HDFStore.append

[jrmylow]

I'll get started with:

• pandas.describe_option
• pandas.reset_option
• pandas.get_option
• pandas.set_option

[jordan-d-murphy]

I'll take:

• pandas.core.groupby.SeriesGroupBy.idxmax
• pandas.core.groupby.SeriesGroupBy.idxmin

[jrmylow]

Would it be helpful to add the good-first-issue label to this? Seems the previous iteration (for EX03?) had that

[jordan-d-murphy]

I think so, but I can't add the label myself. Feel free to add if you have permissions 🙂

[manlattan]

/take