DOC: fix docstring validation errors for pandas.Series

[natmokval]

follow up on issues #56804, #59458 and #58063
pandas has a script for validating docstrings:

pandas/ci/code_checks.sh

Lines 155 to 187 in 0cdc6a4

	-i "pandas.Series.sparse.fill_value SA01" \
	-i "pandas.Series.sparse.from_coo PR07,SA01" \
	-i "pandas.Series.sparse.npoints SA01" \
	-i "pandas.Series.sparse.sp_values SA01" \
	-i "pandas.Series.sparse.to_coo PR07,RT03,SA01" \
	-i "pandas.Series.std PR01,RT03,SA01" \
	-i "pandas.Series.str.capitalize RT03" \
	-i "pandas.Series.str.casefold RT03" \
	-i "pandas.Series.str.center RT03,SA01" \
	-i "pandas.Series.str.decode PR07,RT03,SA01" \
	-i "pandas.Series.str.encode PR07,RT03,SA01" \
	-i "pandas.Series.str.index RT03" \
	-i "pandas.Series.str.ljust RT03,SA01" \
	-i "pandas.Series.str.lower RT03" \
	-i "pandas.Series.str.lstrip RT03" \
	-i "pandas.Series.str.match RT03" \
	-i "pandas.Series.str.normalize RT03,SA01" \
	-i "pandas.Series.str.partition RT03" \
	-i "pandas.Series.str.repeat SA01" \
	-i "pandas.Series.str.replace SA01" \
	-i "pandas.Series.str.rindex RT03" \
	-i "pandas.Series.str.rjust RT03,SA01" \
	-i "pandas.Series.str.rpartition RT03" \
	-i "pandas.Series.str.rstrip RT03" \
	-i "pandas.Series.str.strip RT03" \
	-i "pandas.Series.str.swapcase RT03" \
	-i "pandas.Series.str.title RT03" \
	-i "pandas.Series.str.upper RT03" \
	-i "pandas.Series.str.wrap RT03,SA01" \
	-i "pandas.Series.str.zfill RT03" \
	-i "pandas.Series.struct.dtypes SA01" \
	-i "pandas.Series.to_markdown SA01" \
	-i "pandas.Series.update PR07,SA01" \

Currently, some methods fail docstring validation check.
The task here is:

• take 2-4 methods
• run: scripts/validate_docstrings.py <method-name>
• fix the docstrings according to whatever error is reported
• remove those methods from code_checks.sh script
• commit, push, open pull request

Example:

scripts/validate_docstrings.py pandas.Series.prod

pandas.Series.prod fails with the ES01 and RT03 errors

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

2 Errors found for `pandas.Series.prod`:
        ES01    No extended summary found
        RT03    Return value has no description

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

[ivonastojanovic]

I'll take these:

 -i "pandas.Series.sparse.fill_value SA01" \ 
 -i "pandas.Series.sparse.from_coo PR07,SA01" \ 
 -i "pandas.Series.sparse.npoints SA01" \ 
 -i "pandas.Series.sparse.sp_values SA01" \ 
 -i "pandas.Series.sparse.to_coo PR07,RT03,SA01" \ 

[wenchen-cai]

I'll take these:

 -i "pandas.Series.str.wrap RT03,SA01" \ 
 -i "pandas.Series.str.zfill RT03" \ 

[ivonastojanovic]

Working on these:

 -i "pandas.Series.str.match RT03" \ 
 -i "pandas.Series.str.normalize RT03,SA01" \ 
 -i "pandas.Series.str.repeat SA01" \ 
 -i "pandas.Series.str.replace SA01" \ 

[githubalexliu]

I'll take these:

-i "pandas.Series.struct.dtypes SA01" \ 
-i "pandas.Series.to_markdown SA01" \ 

[hlakams]

Here's a filtered list of pandas.Series docstring issues that still need to be addressed:

        ...
        -i "pandas.Series.dt.as_unit PR01,PR02" \
        ...
        -i "pandas.Series.dt.round PR01,PR02" \
        ...
        -i "pandas.Series.dt.unit GL08" \
        ...
        -i "pandas.Series.pad PR01,SA01" \
        ...

I went ahead and removed methods that were already claimed/addressed by open + merged PRs.
(Last updated 9/2/2024)

[hlakams]

I'll take these:

 -i "pandas.Series.pop SA01" \
 -i "pandas.Series.list.__getitem__ SA01" \
 -i "pandas.Series.list.flatten SA01" \
 -i "pandas.Series.list.len SA01" \
 -i "pandas.Series.reorder_levels RT03,SA01" \
 -i "pandas.Series.sparse.density SA01" \
 -i "pandas.Series.gt SA01" \
 -i "pandas.Series.lt SA01" \
 -i "pandas.Series.ne SA01" \
 -i "pandas.Series.prod RT03" \
 -i "pandas.Series.product RT03" \