CI: Better error control in the validation of docstrings #57879
Conversation
|
Nice work! thank you @datapythonista |
|
with this ticket (#57879), and now that CI: speedup docstring check consecutive runs #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.
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! |
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: Issue 2 to address: Issue 3 to address: Issue 4 to address: ... 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! |
There was a problem hiding this comment.
@mroeschke if you have time, do you mind having a look at this? We changed how we ignore the pending docstring errors, both in #57826 and here again. And PRs fixing docstrings are conflicting, and they'll conflict again after this one. So it'd be good to merge this as soon as reasonable so contributors need to fix the conflicts once.
| ignore_deprecated=False, | ||
| ignore_errors=None, | ||
| ) | ||
| assert exit_status == 0 | ||
| assert exit_status == 3 |
There was a problem hiding this comment.
When calling the script for a single function, until now it always returned an exit status of 0 even when there were errors. We don't really check this status anywhere right now, but I think it makes more sense that it also returns the number of errors, as we do when we call the script for all functions.
This is why I the exit status needs to be changed here.
| assert exit_status == 2*2 | ||
| assert exit_status_ignore_func == exit_status - 1 | ||
| # two functions * two not global ignored errors - one function ignored error | ||
| assert exit_status == 2 * 2 - 1 |
There was a problem hiding this comment.
The diff of all this part seems a bit complex, but I just reordered the two calls since the test was a bit difficult to read before, as it was calling the two functions first, and then asserting the exit codes in the reverse order as they were being called. There is not change in logic other than replacing the error parameter with ignore_errors as in the rest.
| if raw_ignore_errors: | ||
| for obj_name, error_codes in raw_ignore_errors: | ||
| # function errors "pandas.Series PR01,SA01" | ||
| if obj_name != "*": |
There was a problem hiding this comment.
Could we just use a separate flag for ignoring all errors for a specific code?
There was a problem hiding this comment.
I think it's simpler this way. In a follow up PR I'll try to remove the star. So, we'll be able to simply use --ignore-errors PR01. I guess what you don't like is the star?
And I may use None for the key when the error should always be ignored. But since this PR became already too big, I preferred not to also edit the argparse here.
What do you think?
There was a problem hiding this comment.
Yeah the *, while commonplace in other tools, is still a little more opaque to me than --ignore-all CODE or similar.
Not a blocker to me, but would be nice to consider in a followup
Co-authored-by: Matthew Roeschke <[email protected]>
|
Thanks @datapythonista |
|
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! 🙂 |
…57879) * CI: Better error control in the validation of docstrings * Fix CI errors * Fixing tests * Update scripts/validate_docstrings.py Co-authored-by: Matthew Roeschke <[email protected]> --------- Co-authored-by: Matthew Roeschke <[email protected]>
Making the validation of docstrings more robust, main changes:
--ignore_errorsas-i, so the list of errors to ignore is a bit easier to readCC: @dontgoto @jordan-d-murphy