DOC: Fix docs for various offset constructors

[Dr-Irv]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

Multiple places (list is just a sample):

• https://pandas.pydata.org/docs/reference/api/pandas.tseries.offsets.WeekOfMonth.html missing `normalize parameter
• https://pandas.pydata.org/docs/reference/api/pandas.tseries.offsets.BusinessHour.html missing offset parameter
• https://pandas.pydata.org/docs/reference/api/pandas.tseries.offsets.BYearEnd.html missing all parameters

Documentation problem

They are all missing a definition of the constructor, e.g., WeekOfMonth(n=..., normalize=..., week=..., weekday=...) should be at the top for the WeekOfMonth followed by a description of the parameters.

Suggested fix for documentation

All of these should be checked to see if all the parameters are listed correctly. The way they are defined means that positional arguments will work, but maybe we don't want to support that. (If that's the case, that's a separate issue)

The constructors should appear at the top with their arguments, like is done for other classes.

[choudharynishu]

I can help with this @MarcoGorelli. Would it be correct to assume in most cases the definition to be added is similar to 1.0 ? I checked WeekOfMonth from 1.0

[MarcoGorelli]

Hi @choudharynishu - not sure what you mean by similar to 1.0, but what needs doing for WeekOfMonth is to add a description for the normalize parameter

[choudharynishu]

take

[Dr-Irv]

Hi @choudharynishu - not sure what you mean by similar to 1.0, but what needs doing for WeekOfMonth is to add a description for the normalize parameter

The issue goes beyond WeekOfMonth. What ought to be done is twofold:

1. Check for each of the offsets that the list of parameters is correct.
2. Change the documentation generation process so that the parameters to the constructor are listed at the top.

With respect to (2), if you look at https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Index.html, you will see at the top:

class pandas.Index(data=None, dtype=None, copy=False, name=None, tupleize_cols=True)

If you look at any of the offsets, e.g. BusinessDay at https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.tseries.offsets.BusinessDay.html, you see this:

class pandas.tseries.offsets.BusinessDay

I believe for BusinessDay, based on the code, it should be:

class  pandas.tseries.offsets.BusinessDay(n=1, normalize=False, offset=timedelta(0))

In fact, for BusinessDay, the parameter offset is even missing from the list of parameters on the doc page.

So to close this issue, a complete review of all the offsets should be done, with changes made to reflect the correct constructor and the parameters.

Here's a list (under details) that I created by doing some grep on the doc source:

• DateOffset
• BusinessDay
• BusinessHour
• CustomBusinessDay
• CustomBusinessHour
• MonthEnd
• MonthBegin
• BusinessMonthEnd
• BusinessMonthBegin
• CustomBusinessMonthEnd
• CustomBusinessMonthBegin
• SemiMonthEnd
• SemiMonthBegin
• Week
• WeekOfMonth
• LastWeekOfMonth
• BQuarterEnd
• BQuarterBegin
• QuarterEnd
• QuarterBegin
• BYearEnd
• BYearBegin
• YearEnd
• YearBegin
• FY5253Quarter
• Easter
• Tick
• Day
• Hour
• Minute
• Second
• Milli
• Micro
• Nano
• Frequencies

[Snehaaa18]

is this issue open ?? I am a beginner contributor

[MarcoGorelli]

yup! you're both (@Snehaaa18 and @choudharynishu) welcome to work on this, there are a lot of offsets which need updating

if you find an offset's docstring to work on, which has a parameter not documenting, and would like to work on it, perhaps comment here so we don't duplicate work

[Snehaaa18]

Take