CI: Better error control in the validation of docstrings
State: closed

Making the validation of docstrings more robust, main changes:

- If we ignore an error that doesn't fail, the CI will report it and break (there were 30 errors being ignored that are already fixed and removed from the list of ignores here)
- Instead of specifying all the errors to validate (that are all but one now) we can specify errors to skip (there is one only that we skip, the lack of an extended summary in a docstring). This simplifies the script a bit
- In case an unknown error code is used when ignoring errors, the message should be more descriptive
- I created an alias for `--ignore_errors` as `-i`, so the list of errors to ignore is a bit easier to read

CC: @dontgoto @jordan-d-murphy 

Labels:
name: Docs
name: CI
description: Continuous Integration

Comments:
Nice work! thank you @datapythonista 
with this ticket (#57879), and now that [CI: speedup docstring check consecutive runs #57826](https://github.com/pandas-dev/pandas/pull/57826) is merged in, I'm closing the following issues And opening a new issue to address these based on the new approach we've implemented. 

> [DOC: fix GL08 errors in docstrings](https://github.com/pandas-dev/pandas/issues/57443)
> [DOC: fix PR01 errors in docstrings](https://github.com/pandas-dev/pandas/issues/57438)
> [DOC: fix PR07 errors in docstrings](https://github.com/pandas-dev/pandas/issues/57420)
> [DOC: fix SA01 errors in docstrings](https://github.com/pandas-dev/pandas/issues/57417)
> [DOC: fix RT03 errors in docstrings](https://github.com/pandas-dev/pandas/issues/57416)
> [DOC: fix PR02 errors in docstrings](https://github.com/pandas-dev/pandas/issues/57111)

Thanks for all the work that's gone into this! this is a much cleaner approach, and fixing these will now be more straightforward. Big win in my opinion! 
> And opening a new issue to address these based on the new approach we've implemented.

What I'd do is create a master issue if there is not one already to fix the docstrings, and then create smaller issues labelled as "good first issue". For example:

Issue 1 to address:
```
        -i pandas.Categorical.__array__ SA01\
        -i pandas.Categorical.codes SA01\
        -i pandas.Categorical.dtype SA01\
        -i pandas.Categorical.from_codes SA01\
        -i pandas.Categorical.ordered SA01\
        -i pandas.CategoricalDtype.categories SA01\
        -i pandas.CategoricalDtype.ordered SA01\
        -i pandas.CategoricalIndex.codes SA01\
        -i pandas.CategoricalIndex.ordered SA01\
```

Issue 2 to address:
```
        -i pandas.HDFStore.append PR01,SA01\
        -i pandas.HDFStore.get SA01\
        -i pandas.HDFStore.groups SA01\
        -i pandas.HDFStore.info RT03,SA01\
        -i pandas.HDFStore.keys SA01\
        -i pandas.HDFStore.put PR01,SA01\
        -i pandas.HDFStore.select SA01\
        -i pandas.HDFStore.walk SA01\
```

Issue 3 to address:
```
        -i pandas.Int16Dtype SA01\
        -i pandas.Int32Dtype SA01\
        -i pandas.Int64Dtype SA01\
        -i pandas.Int8Dtype SA01\
```

Issue 4 to address:
```
        -i pandas.Interval PR02\
        -i pandas.Interval.closed SA01\
        -i pandas.Interval.left SA01\
        -i pandas.Interval.mid SA01\
        -i pandas.Interval.right SA01\
```

...

I think it'll make the work of contributors easier by addressing those in groups. In particular, the see also section of many of those would be quite easy since the docstrings they'll be cross-referencing each other in many cases.

If you don't have triagge permissions in this repo, please let me know, I'll give them to you, so you can labelled the issues as "good first issue" and anything else needed.
Thanks for the guidance, @datapythonista ! 

I agree, that sounds like a great approach. I'll set it up once this gets merged in so I can grab the updated code snippets from main. 

I don't have those permissions, it would be helpful if you can grant them to me. Thank you! 


That's some great simplifications for the error handling logic!
Thanks @datapythonista 
Opened [DOC: Enforce Numpy Docstring Validation (Parent Issue) #58063](https://github.com/pandas-dev/pandas/issues/58063) as a parent issue for fixing docstrings based on the refactoring in code_checks.sh 

Feel free to swing by and help out! 🙂