Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Improve error message to show correct order #23652

Merged
merged 5 commits into from
Nov 17, 2018
Merged

DOC: Improve error message to show correct order #23652

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ba200af
BUG: Work-around a numpy regression
neirbowj Dec 9, 2013
182110b
DOC: Mention #5666 in 0.13.0 release notes
neirbowj Dec 9, 2013
cc429cf
Merge remote-tracking branch 'upstream/master'
dat-boris Nov 12, 2018
672d2b5
DOC: Display correct order for sections. Fix #23644
dat-boris Nov 12, 2018
9a435ce
Flake8
dat-boris Nov 12, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions scripts/tests/test_validate_docstrings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -738,8 +738,8 @@ def test_bad_generic_functions(self, func):
('BadGenericDocStrings', 'unknown_section',
('Found unknown section "Unknown Section".',)),
('BadGenericDocStrings', 'sections_in_wrong_order',
('Wrong order of sections. "See Also" should be located before '
'"Notes"',)),
('Sections are in the wrong order. Correct order is: Parameters, '
'See Also, Examples',)),
('BadSeeAlso', 'desc_no_period',
('Missing period at end of description for See Also "Series.iloc"',)),
('BadSeeAlso', 'desc_first_letter_lowercase',
Expand Down
34 changes: 14 additions & 20 deletions scripts/validate_docstrings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,8 +74,8 @@
'whitespace only',
'GL06': 'Found unknown section "{section}". Allowed sections are: '
'{allowed_sections}',
'GL07': 'Wrong order of sections. "{wrong_section}" should be located '
'before "{goes_before}", the right order is: {sorted_sections}',
'GL07': 'Sections are in the wrong order. Correct order is: '
'{correct_sections}',
'SS01': 'No summary found (a short summary in a single line should be '
'present at the beginning of the docstring)',
'SS02': 'Summary does not start with a capital letter',
Expand Down Expand Up @@ -599,24 +599,18 @@ def validate_one(func_name):
if re.match("^ *\t", line):
errs.append(error('GL05', line_with_tabs=line.lstrip()))

unseen_sections = list(ALLOWED_SECTIONS)
for section in doc.section_titles:
if section not in ALLOWED_SECTIONS:
errs.append(error('GL06',
section=section,
allowed_sections=', '.join(ALLOWED_SECTIONS)))
else:
if section in unseen_sections:
section_idx = unseen_sections.index(section)
unseen_sections = unseen_sections[section_idx + 1:]
else:
section_idx = ALLOWED_SECTIONS.index(section)
goes_before = ALLOWED_SECTIONS[section_idx + 1]
errs.append(error('GL07',
sorted_sections=' > '.join(ALLOWED_SECTIONS),
wrong_section=section,
goes_before=goes_before))
break
unexpected_sections = [section for section in doc.section_titles
if section not in ALLOWED_SECTIONS]
for section in unexpected_sections:
errs.append(error('GL06',
section=section,
allowed_sections=', '.join(ALLOWED_SECTIONS)))

correct_order = [section for section in ALLOWED_SECTIONS
if section in doc.section_titles]
if correct_order != doc.section_titles:
errs.append(error('GL07',
correct_sections=', '.join(correct_order)))

if not doc.summary:
errs.append(error('SS01'))
Expand Down