pandas: DOC: fix SA05 errors in docstrings

@williamking1221 What we were talking about was adding SA05 here

https://github.com/pandas-dev/pandas/blob/43209e798dd86237a39b667932b4ec438a4ae059/ci/code_checks.sh#L68-L70

when we remove the block here https://github.com/pandas-dev/pandas/blob/43209e798dd86237a39b667932b4ec438a4ae059/ci/code_checks.sh#L3185-L3187

Ah gotcha! Thanks! Fixed it in recent commit.

I believe if this PR goes through, this issue can be closed.

I don’t see it, could you please double check if it went through?

Thanks!

Hi @jordan-d-murphy

Thanks for this! Btw, is your comment on the PR I raised?

@williamking1221 Yeah here’s some info on the ES01s from what I understand.

I’ll show two examples to illustrate: Running the following scripts/validate_docstrings.py --format=actions --errors=ES01 pandas.Categorical.map outputs:

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

Docstring for "pandas.Categorical.map" correct. :)

and running scripts/validate_docstrings.py --format=actions --errors=ES01 pandas.Categorical.__array__ outputs

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

3 Errors found for `pandas.Categorical.__array__`:
	ES01	No extended summary found
	PR01	Parameters {'dtype'} not documented
	SA01	See Also section not found

If we look at the docstrings, we can see a difference:

pandas.Categorical.array (fails with one ES01 - see the higlighted single line summary)

pandas.Categorical.map (passes with no ES01 - See highlighted Extended Summary)

Adding an extended summary fixes this:

updated output:

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

2 Errors found for `pandas.Categorical.__array__`:
	PR01	Parameters {'dtype'} not documented
	SA01	See Also section not found

I dont’ know if that answers the question, but hopefully that’s a start.

EDIT: I just want to be clear this is an example of HOW to resolve the issue, but call out that we shouldn’t just start adding meaningless extended summaries in order to pass the checks.

@williamking1221 https://github.com/pandas-dev/pandas/issues/57440 for ESO1s

I’ll take

        pandas.plotting.bootstrap_plot
        pandas.plotting.radviz

For the ES01 I have opened a PR to get these addressed. See https://github.com/pandas-dev/pandas/pull/57359

I have a merge conflict to resolve in order to get that merged, and then I’ll open an Issue to fix all ES01 errors. (Similar to this issue)

Hopefully that will happen later today when I get home from work. I need to do that from my personal laptop.

But feel free to fix it if you want to! The ultimate goal of All these issues I’m opening is to have correct docstrings for all the functions. I’m segmenting them out to give some structure to the process, but a fully correct docstring for each function is the end goal!

(Typing this from my phone is it’s hard to explain the fix for ES01, but when I get back to my personal laptop I’ll share more info on those fixes. For PRs opened under this issue it’s okay if other errors show up, as long as the SA05 errors are resolved.)

I’ll take

        pandas.core.resample.Resampler.first
        pandas.core.resample.Resampler.last

Seems like both are ok, even without changes. I’ll just remove these two then.

@jordan-d-murphy

Got it, Thanks.

Hey @jordan-d-murphy

I can take SeriesGroupBy : first and last once my previous PR gets merged.

I’ll take pandas.core.groupby.DataFrameGroupBy.first pandas.core.groupby.DataFrameGroupBy.last

I’ll take

     pandas.PeriodIndex.asfreq
     pandas.arrays.ArrowStringArray
     pandas.arrays.StringArray

I don’t have permission to add them, but this could probably use some labels:

• CI
• Docs
• good first issue