DOC: Fix docstring quotes in pandas.PeriodIndex

[abkosar]

I am trying to work on fixing the docstring errors GL01 and GL02. The validate_docstrings.py gave a lot of them so I picked pandas.PeriodIndex:

pandas.PeriodIndex.day: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.day: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.dayofweek: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.dayofweek: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.dayofyear: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.dayofyear: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.days_in_month: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.days_in_month: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.daysinmonth: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.daysinmonth: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.hour: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.hour: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.minute: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.minute: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.month: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.month: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.quarter: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.quarter: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.second: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.second: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.week: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.week: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.weekday: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.weekday: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.weekofyear: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.weekofyear: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.PeriodIndex.year: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.PeriodIndex.year: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)

However I need some help navigating to the related docstrings for each of these attributes. I thought I could find the PeriodIndex class at pandas.core.indexes.period which I did but I can't find any of the attributes (so the docstrings) in that file.

I am fairly new to contributing to Pandas so maybe I am making a dumb mistake or looking at the wrong place so I would appreciate some guidance.

Thanks!

[jbrockmendel]

Those attributes are inherited via PeriodArray, which is in pandas.core.arrays.period

[abkosar]

Hey @jbrockmendel -- I think I found it. So when I did this it fixed the days_in_month, is this the right way to do it:

days_in_month = _field_accessor("days_in_month", 
                                11, 
                                """
                                The number of days in the month
                                """
)

[jbrockmendel]

My guess is it will want a period at the end of the docstring, but that looks about right.

[abkosar]

@jbrockmendel -- Ok so should I do a PR for pandas.PeriodIndex? The validate_docstrings.py doesn't give any errors now.

[jbrockmendel]

That'd be great, thanks.

[abkosar]

And I will continue on other GL01 and GL02 errors in this same manner. Thanks!

[WillAyd]

I see one other issue for GL01 - do we have a master tracking issue for this? If not @abkosar can you start one?

@datapythonista

[abkosar]

@WillAyd It started with #23870. I first started working on this whole thing in that issue. However then it got closed and @datapythonista told me that I can continue working on them and create PRs on the way (that's how I interpreted it).

So that's what I did but I can also create an issue for GL01 and GL02, work on all of them and then create a PR.

Tell me which is the best practice and I will do that, thanks!

[datapythonista]

I'm planning to start working in depth in those issues with the people I'm mentoring, probably in around a week. You can leave the issue creation with me, thanks!

[abkosar]

Sounds good, I will find another issue to work on then, thanks!

[WillAyd]

You can keep working the PR you have open

[abkosar]

Yeah, I just ran black against the modified files and pushed again. I think I did it the first time but forgot to do it for the second file I modified.

This is great learning, especially with the library that I use the most every day, glad to be of help!

[datapythonista]

@abkosar not a problem at all that you keep working on those fixes. We have some thousands of things to fix in the documentation, and I'll spend time on creating the issues for people to know about them and fix them, but any work you do (now finding the problems yourself, or later based on the issues) it's very welcome.

[abkosar]

@datapythonista

I will continue working on GL01 and GL02 then but wait for you to create the issues to do the PRs.

Thanks!

[datapythonista]

My recommendation would be that if you work on fixing these errors, you open a PR every time you have some fixed, and you stop working on them (even if it's for a day or two). Not sure when I'll have the issues created, but if you keep opening relatively small PRs, it's very difficult that we overlap or repeat work.

Also, if you can tag me in the PRs, that would be great, so I can review and get them merged faster.

Thanks!