DOC: Improvement docstring of DataFrame.rank() #25328
Conversation
Codecov Report
@@ Coverage Diff @@
## master #25328 +/- ##
=======================================
Coverage 91.72% 91.72%
=======================================
Files 173 173
Lines 52831 52831
=======================================
Hits 48458 48458
Misses 4373 4373
Continue to review full report at Codecov.
|
Codecov Report
@@ Coverage Diff @@
## master #25328 +/- ##
==========================================
+ Coverage 91.72% 91.98% +0.26%
==========================================
Files 173 175 +2
Lines 52831 52374 -457
==========================================
- Hits 48458 48175 -283
+ Misses 4373 4199 -174
Continue to review full report at Codecov.
|
|
lgtm. @WillAyd over to you. |
|
@EdAbati can you merge master and address comments above? Should be simple fixes |
|
Hi @WillAyd , I have solved the docstring validation errors above. Please let me know if I should make any changes. Thanks |
pandas/core/generic.py
Outdated
| * min: lowest rank in the group. | ||
| * max: highest rank in the group. | ||
| * first: ranks assigned in order they appear in the array. | ||
| * dense: like 'min', but rank always increases by 1 between groups. |
There was a problem hiding this comment.
Instead of adding periods to the end of each bullet what if you just moved the bullets above the short description you've added? Very minor but adding a period at the end of a bullet point is a hack to get validation to pass so would prefer not to do that
There was a problem hiding this comment.
Hi @WillAyd ,
I have tried to move the bullets above the short description, but the docstring validation will then produce these errors:
2 Errors found:
Parameter "method" description should start with a capital letter
Parameter "na_option" description should start with a capital letter
There was a problem hiding this comment.
I just noticed that for example in the pandas.DataFrame.any docstring there is a period at the end of each bullet and the validation does not return any error.
(If I understood correctly, this docstring is built from _bool_doc.)
How do you think it is the best way to use bullet lists?
Would you prefer that I substitute the 2 bullet lists with a description instead?
There was a problem hiding this comment.
Right the example you mentioned for .any is exactly what I'm trying to avoid because I think it would look strange if every bulleted list in our documentation ends with periods just to get a validation check to pass.
Bullets are fine just add a very short description at the end to get validation to pass. Alternately there is an issue open to address the period error showing up for bullets in #20298 which would welcome a PR for
|
@EdAbati can you address previous comment and merge master? |
|
Hi @WillAyd, I could not find a nice description for the parameters of this method without using bullet points. If the PR is accepted, I was planning to only remove the bullet points at the end of each bullet. Edit : I have just created a PR #25786 |
|
can you merge master |
|
@EdAbati can you merge master? Don't think we need to wait on your other PR to get this one through |
|
Hi @WillAyd , Apologies for the delay, I have been away and very busy lately. I have just removed the bullet points in the 2 parameter lists. I will soon update the other PR as well. |
|
@EdAbati sorry for having taken so long on my end. This is a nice update - great job for a first contribution! |
git diff upstream/master -u -- "*.py" | flake8 --diffI have made the changes requested in the pull request #23263
This is the output of the docstring validation:
In the previous pull request I have been told that I could ignore these 3 errors.
Please let me know if I can further improve the docstring.
Thanks a lot