DOC: Adding validation of the section order in docstrings #23607
Conversation
|
Hello @datapythonista! Thanks for submitting the PR.
|
Codecov Report
@@ Coverage Diff @@
## master #23607 +/- ##
=======================================
Coverage 92.25% 92.25%
=======================================
Files 161 161
Lines 51260 51260
=======================================
Hits 47290 47290
Misses 3970 3970
Continue to review full report at Codecov.
|
|
@TomAugspurger do you mind having a quick look here, and merge if you're happy? I'd like to create the issue to fix the wrong section names. |
| ('Found unknown section "Unknown Section".',)), | ||
| ('BadGenericDocStrings', 'sections_in_wrong_order', | ||
| ('Wrong order of sections. "See Also" should be located before ' | ||
| '"Notes"',)), |
There was a problem hiding this comment.
To make sure I understand the error message, we say "See Also should be located before Notes" because it's the section immediately preceding notes. But the "users" docstring in this case doesn't have a "Notes" section, so that's slightly confusing.
I was hoping we could instead say "See Also should be located before Examples", but that's not quite right either, because if you have three out of order sections, you would want to skip back two sections, if that makes sense...
So I guess my only comment is, "this error message is potentially confusing. But I don't know how to improve it". If you see an easy way to improve it, push it here. Otherwise +1 from me.
There was a problem hiding this comment.
Good point, I 100% agree. I couldn't find a better way to report it, without dong something too complex and possibly even more misleading.
But I think it should be all right, as in the error message I show the order of all sections (is not shown in the test, but will be displayed to the users).
May be after this starts to be used someone comes with a better idea. But I think it should be good enough.
There was a problem hiding this comment.
But I think it should be all right, as in the error message I show the order of all sections (is not shown in the test, but will be displayed to the users).
Ah great. That sounds fine.
…fixed * upstream/master: DOC: avoid SparseArray.take error (pandas-dev#23637) CLN: remove incorrect usages of com.AbstractMethodError (pandas-dev#23625) DOC: Adding validation of the section order in docstrings (pandas-dev#23607) BUG: Don't over-optimize memory with jagged CSV (pandas-dev#23527) DEPR: Deprecate usecols as int in read_excel (pandas-dev#23635) More helpful Stata string length error. (pandas-dev#23629) BUG: astype fill_value for SparseArray.astype (pandas-dev#23547) CLN: datetimelike arrays: isort, small reorg (pandas-dev#23587) CI: Check in the CI that assert_raises_regex is not being used (pandas-dev#23627) CLN:Remove unused **kwargs from user facing methods (pandas-dev#23249)
…#23607) * Adding validation of the section order in docstrings * Updating allowed sections
…#23607) * Adding validation of the section order in docstrings * Updating allowed sections
…#23607) * Adding validation of the section order in docstrings * Updating allowed sections
…#23607) * Adding validation of the section order in docstrings * Updating allowed sections
git diff upstream/master -u -- "*.py" | flake8 --diff