DOC: fix ES01 errors in docstrings

[jordan-d-murphy]

Pandas has a script for validating docstrings:

https://github.com/pandas-dev/pandas/blob/1ca9b5871dc71353185b48362bc84e666229810d/ci/code_checks.sh#L144-L1185

Currently, some methods fail the ES01 check.

The task here is:

• take 2-4 methods
• run: scripts/validate_docstrings.py --format=actions --errors=ES01 method-name
• check if validation docstrings passes for those methods, and if it’s necessary fix the docstrings according to whatever error is reported
• remove those methods from code_checks.sh
• commit, push, open pull request

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

[jordan-d-murphy]

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

• CI
• Docs
• good first issue

[jordan-d-murphy]

addresses https://github.com/pandas-dev/pandas/pull/57359

[williamking1221]

I'll take

     pandas.Categorical.__array__
     pandas.Categorical.as_ordered
     pandas.Categorical.as_unordered
     pandas.Categorical.ordered
     pandas.Categorical.remove_unused_categories
     pandas.Categorical.rename_categories

[v-lozko]

I'll take

    pandas.DataFrame.T\
    pandas.DataFrame.agg\

[v-lozko]

There is a bit of a circular error happening with this task. Running scripts/validate_docstrings.py --format=actions --errors=ES01 method-name generates an error saying that an extended summary is needed. However, once one is added it states that extended summary is not one of the allowed sections

[jordan-d-murphy]

Opened a fix for pandas.Flags

[YashpalAhlawat]

Opened fix for to_csv method. Will take more once this get merged.

[YashpalAhlawat]

Raised a PR for fix of ES01 for below methods:

• pandas.HDFStore.get
• pandas.HDFStore.info
• pandas.HDFStore.keys
• pandas.HDFStore.put

[jordan-d-murphy]

opened a PR for pandas.CategoricalDtype

[mroeschke]

@jordan-d-murphy what do you think about intentionally not enforcing ES01 for the docstrings? In my opinion if they just redescribe the parameter section or tell something that would be clearer in an example, I'm skeptical of it's value

[jordan-d-murphy]

That's a fair point, if it's not adding enough value to be worth enforcing, I can open a PR to remove the block that enforces it. @mroeschke

[v-lozko]

@jordan-d-murphy will this issue then be closed because of https://github.com/pandas-dev/pandas/pull/57625? I had taken a couple methods to update but haven't addressed them yet because of an open question

[mroeschke]

Closing due to https://github.com/pandas-dev/pandas/pull/57625

[jordan-d-murphy]

yup @v-lozko I opened some more issues that are similar if you'd like to help work on these! DOC: fix RT03 errors in docstrings DOC: fix SA01 errors in docstrings DOC: fix PR07 errors in docstrings DOC: fix PR01 errors in docstrings DOC: fix GL08 errors in docstrings

[jordan-d-murphy]

Opened DOC: Enforce Numpy Docstring Validation (Parent Issue) #58063 as a parent issue for fixing docstrings based on the refactoring in code_checks.sh

Feel free to swing by and help out! 🙂