DOC: Enforce Numpy Docstring Validation (Parent Issue)

[jordan-d-murphy]

Pandas has a script for validating docstrings:

https://github.com/pandas-dev/pandas/blob/c468028f5c2398c04d355cef7a8b6a3952620de2/ci/code_checks.sh#L68-L1266

Currently, some methods fail some of these checks.

The work will be broken up into several tickets, to address the work in issues of a more manageable size.

Issues: DOC: Enforce Numpy Docstring Validation | pandas.Categorical #58064 DOC: Enforce Numpy Docstring Validation | pandas.DataFrame #58065 DOC: Enforce Numpy Docstring Validation | pandas.Datetime #58066 DOC: Enforce Numpy Docstring Validation | pandas.ExcelFile through pandas.HDFStore #58067 DOC: Enforce Numpy Docstring Validation | pandas.Index #58068 * Additional Issues will be added here as they are created

For each Issue, the task is:

1. take 1-5 methods

2. run: scripts/validate_docstrings.py --format=actions <method-name>

example command: scripts/validate_docstrings.py --format=actions pandas.Categorical.__array__ example output:

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

2 Errors found for `pandas.Categorical.__array__`:
	ES01	No extended summary found
	SA01	See Also section not found

3. check if validation docstrings passes for those methods, and if it’s necessary fix the docstrings according to whatever error is reported. Note: We've chosen to ignore ES01 errors, these are not required to be fixed.

4. remove those methods from code_checks.sh if all errors are cleared and the docstring is correct, otherwise, remove the specific error that was fixed from the list of errors for that method.

5. 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

thanks @datapythonista for the inspiration for this issue!

[jordan-d-murphy]

@datapythonista can you take a look over this? We had discussed this a week or so ago after the refactoring in code_checks.sh ( #57879 & #57908 ) so I wanted to make sure it's in line with what you were thinking. if it looks good to you, I'll go ahead and create issues for the rest of the method categories. Also, I did try to add labels to the child issues, but It doesn't seem to let me for some reason.

[ThomasBur]

--error was removed as an argument of scripts/validate_docstrings.py in #57879 so the example command won't work.

People can exclude it, instead checking with: scripts/validate_docstrings.py --format=actions <method-name>

[jordan-d-murphy]

Ah gotcha thanks @ThomasBur I'll update this in all the issues

[jordan-d-murphy]

@ThomasBur I updated the example above, can you confirm it looks correct? (I've updated the examples in the other issues with the same fix)

[Aloqeely]

Looks good, but you'll need to start the command with python (followed by scripts/validate_docstrings.py --format=actions <method-name>), even though it might seem obvious it's better to be clear.

[jordan-d-murphy]

I think python is not required if the development virtual environment is activated, which I believe we should be encouraging.

[tuhinsharma121]

@jordan-d-murphy Mr murphy can you please add https://github.com/pandas-dev/pandas/issues/58498 to the body of the parent issue?