DOC: Fix docs for various offset constructors

[Dr-Irv]

Pandas version checks

• [X] 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

[anshuman0123]

Hey , I am totally new to open source contribution . Please someone help me in making contribution . My first question is . Where the files are stored in which I have to work on . Give me the exact location in this repo

[Dr-Irv]

Hey , I am totally new to open source contribution . Please someone help me in making contribution . My first question is . Where the files are stored in which I have to work on . Give me the exact location in this repo

Two other people are working on this issue. To get started with contributing, see https://pandas.pydata.org/pandas-docs/stable/development/contributing.html

[natmokval]

I'd like to work on it. I will add parameters to offsets classes: BYearEnd, BusinessHour, WeekOfMonth.

[dullibri]

I would like to work on Second, Hour and Day

[natmokval]

I would like to work on FY5253 and FY5253Quarter: add missing parameter and examples.

I will add missing parameters "n" \ "normalize" \ "offset" to BusinessDay, Week , LastWeekOfMonth, CustomBusinessHour, and BusinessDay as well.

[vinitaparasrampuria]

Hi! Can I work on this if the issue is still open?

[Dr-Irv]

Hi! Can I work on this if the issue is still open?

Yes, I will assign to you as well. See the comment at https://github.com/pandas-dev/pandas/issues/52431#issuecomment-1499446218 for the list of everything that needs to be checked.

[mohmmadAyesh]

Hi it seem all of them get parameters except dateOffset which is a standard class and Frequencies I would like to contribute I didnt find frequencies in offset can i contribute to this or is there any other contribute in this issue :)

[Anh-HoDac]

Hi, I noticed that the Tick class is not yet updated, so I would like to work on it.

[Abhinav00077]

hey there is the issue still open, i am a beginner contributor just need to know how to contribute to it, would be a great help

[enesyesil]

Hey, is the issue still open, I am a beginner. I will be happy to contribute to it. thanks

[shriyase]

Hey as a beginner I'd like to contribute!

[Dr-Irv]

@Abhinav00077 @enesyesil @shriyase we've had a lot of contributions to resolving this issue. What probably needs to be done at this point is to create a checklist from the list in this comment (open the "Details" at the bottom) https://github.com/pandas-dev/pandas/issues/52431#issuecomment-1499446218 as a new comment in this PR and indicate which of the classes have already had their docs fixed. Then we know which ones are left to do, and any of you can grab one of them to fix.

[NavaneetthaSundararaj]

@Dr-Irv here is a checklist from the list of comments based on https://github.com/pandas-dev/pandas/issues/52431#issuecomment-2183414515:

• [x] DateOffset https://github.com/pandas-dev/pandas/issues/52431#issuecomment-2267825934
• [x] BusinessDay https://github.com/pandas-dev/pandas/pull/54635
• [x] BusinessHour https://github.com/pandas-dev/pandas/pull/53183
• [x] CustomBusinessDay https://github.com/pandas-dev/pandas/issues/52431#issuecomment-2267727631
• [x] CustomBusinessHour https://github.com/pandas-dev/pandas/pull/54635
• [x] MonthEnd https://github.com/pandas-dev/pandas/pull/53420
• [x] MonthBegin https://github.com/pandas-dev/pandas/pull/53420
• [x] BusinessMonthEnd https://github.com/pandas-dev/pandas/pull/53420
• [x] BusinessMonthBegin https://github.com/pandas-dev/pandas/pull/53420
• [x] CustomBusinessMonthEnd https://github.com/pandas-dev/pandas/pull/55328
• [x] CustomBusinessMonthBegin https://github.com/pandas-dev/pandas/pull/55328
• [x] SemiMonthEnd https://github.com/pandas-dev/pandas/issues/52431#issuecomment-2267727631
• [x] SemiMonthBegin https://github.com/pandas-dev/pandas/issues/52431#issuecomment-2267727631
• [x] Week https://github.com/pandas-dev/pandas/pull/54635
• [x] WeekOfMonth https://github.com/pandas-dev/pandas/pull/53183
• [x] LastWeekOfMonth https://github.com/pandas-dev/pandas/pull/54635
• [x] BQuarterEnd https://github.com/pandas-dev/pandas/pull/53378
• [x] BQuarterBegin https://github.com/pandas-dev/pandas/pull/53378
• [x] QuarterEnd https://github.com/pandas-dev/pandas/pull/53378
• [x] QuarterBegin https://github.com/pandas-dev/pandas/pull/53378
• [x] BYearEnd https://github.com/pandas-dev/pandas/pull/53183
• [x] BYearBegin https://github.com/pandas-dev/pandas/pull/53280
• [x] YearEnd https://github.com/pandas-dev/pandas/pull/53280
• [x] YearBegin https://github.com/pandas-dev/pandas/pull/53280
• [x] FY5253Quarter https://github.com/pandas-dev/pandas/pull/54608
• [x] FY5253 https://github.com/pandas-dev/pandas/pull/54608
• [x] Easter https://github.com/pandas-dev/pandas/pull/53476
• [x] Tick https://github.com/pandas-dev/pandas/issues/52431#issuecomment-2267825934
• [x] Day https://github.com/pandas-dev/pandas/pull/54427
• [x] Hour https://github.com/pandas-dev/pandas/pull/54427
• [x] Minute https://github.com/pandas-dev/pandas/pull/54427
• [x] Second https://github.com/pandas-dev/pandas/pull/54427
• [x] Milli https://github.com/pandas-dev/pandas/pull/56336
• [x] Micro https://github.com/pandas-dev/pandas/pull/56336
• [x] Nano https://github.com/pandas-dev/pandas/pull/56336
• [x] Frequencies https://github.com/pandas-dev/pandas/issues/52431#issuecomment-2267825934

[NavaneetthaSundararaj]

I would like to work on this:

CustomBusinessMonthEnd CustomBusinessMonthBegin SemiMonthEnd SemiMonthBegin CustomBusinessDay

[Siniade]

Hi! I'm a beginner contributor and would like to work on this as well. I see that there are 3 classes remaining from the checklist above. I would like to work on these 3:

DateOffset Tick Frequencies

[Siniade]

take

[Siniade]

@Dr-Irv When using the offsets methods, Tick is not generally directly called upon. Instead the Tick object is initiated when we call its subclasses Hour, Minute, Second, Milli, etc. The Tick class is similar to the BaseOffset or the BusinessMixin classes that are not directly called upon but have subclasses through which they are initiated. In this case doesn't it make sense to not have a public documentation page for the Tick class?

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.

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)

Also regarding this issue, I noticed that the class pandas.Index is defined as a python class, however the pandas.tseries.offsets are defined as Cython cdef classes. Could that potentially be the reason it doesn't display the attributes at the top of the page?

[Dr-Irv]

@Dr-Irv When using the offsets methods, Tick is not generally directly called upon. Instead the Tick object is initiated when we call its subclasses Hour, Minute, Second, Milli, etc. The Tick class is similar to the BaseOffset or the BusinessMixin classes that are not directly called upon but have subclasses through which they are initiated. In this case doesn't it make sense to not have a public documentation page for the Tick class?

I'm not the one to make the decision here about whether we continue to document Tick but Tick is documented at https://pandas.pydata.org/pandas-docs/stable/reference/offset_frequency.html#tick and https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.tseries.offsets.Tick.html#pandas.tseries.offsets.Tick so given that it has been documented before, we should continue to document it and include the docstring for the constructor

Also regarding this issue, I noticed that the class pandas.Index is defined as a python class, however the pandas.tseries.offsets are defined as Cython cdef classes. Could that potentially be the reason it doesn't display the attributes at the top of the page?

Possibly. I'm not familiar with how the docs are built here - I just raised the issue!

[Siniade]

@Dr-Irv Got it. Thank you for clarifying! I'll update the Tick docstrings.

[sunlight798]

Hello, is the issue still open. I am a beginner. I will be happy to contribute to it. how can I obtain a problem that can be solved?

[yoav-edelist]

Also curious as to the status of this issue. @Siniade @NavaneetthaSundararaj Where do things stand?

[sainivas-99]

Hello,

I am just getting started with contribution and would like to contribute, I see that the status of the DateOffSet is still pending. I can work on it, but am not sure if @Siniade is still working on it. Can I take this?