Open datapythonista opened 5 years ago
@datapythonista, thanks so much for your advice. We'd been attempting to eliminate duplication of effort, but needed a better method.
Is this still open
Running ./scripts/validate_docstrings.py --errors=EX02
should say whether there are any remaining @goodship1.
Saw this in validate_docstrings.py
and thought it was useful to share.
The errors codes are defined as:
- First two characters: Section where the error happens:
* GL: Global (no section, like section ordering errors)
* SS: Short summary
* ES: Extended summary
* PR: Parameters
* RT: Returns
* YD: Yields
* RS: Raises
* WN: Warns
* SA: See Also
* NT: Notes
* RF: References
* EX: Examples
- Last two characters: Numeric error code inside the section
take
is there still work to be done on this issue? can i take it if there is ?
Sure take it!
On Thu, May 28, 2020 at 5:02 PM willpeppo notifications@github.com wrote:
is there still work to be done on this issue? can i take it if there is ?
— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/pandas-dev/pandas/issues/27977#issuecomment-635605976, or unsubscribe https://github.com/notifications/unsubscribe-auth/AATCQHZPKABMUPS25NPTTYDRT3GOVANCNFSM4IMQOPIQ .
take
Is there still work that needs to be done on this?
Historically, there was no validation on how docstrings were written. Some conventions were usually followed, but as the project grew, it was more difficult to ensure that all the API documentation pages are consistent, and don't have mistakes.
For the last two years, we've been implementing all sorts of validations to make sure every class, method, function and attribute is correctly documented.
The list of validations can be found here in the script that validates them: https://github.com/pandas-dev/pandas/blob/master/scripts/validate_docstrings.py#L77
Many of them have already been fixed in all the pages, and they could be added to the CI so they are not reintroduced again. The list of errors currently validated can be seen at the CI script: https://github.com/pandas-dev/pandas/blob/master/ci/code_checks.sh#L267
The list of pending errors making the difference is:
Some of them makes more sense to work when fixing the content of an object (like adding the description, or objects that simply don't have any documentation).
But some of them are just formatting errors, those are the ones I'd start with:
To find errors for one of them you can use:
Or for errors that makes sense to address together:
This should give the list of errors to fix. We've got a list of steps to follow when fixing a docstring that it can be useful to you at: https://python-sprints.github.io/pandas/dashboard.html
VERY IMPORTANT The main challenge will be not repeating the same work as other sprinters, which is very frustrating, and happened massively at every sprint. My recommendation is BEFORE doing any work, to create an issue for the error code you plan to work on (check that it hasn't already been created). In the error write the list of errors that
validate_docstrings.py
returns. Then in a comment, take 10 of them, and write that you're going to fix them. Other people can work on a different 10. When opening a PR, reference the issue.I created an issue for reference: #27976
Good luck!