Skip to content

Commit 795afa8

Browse files
authored
ENH: Better warning for sections. (#278)
* ENH: Better warning for sections. 1) if the number of -/= is too short/ too long warn, Especially too short it won't be detected as a section. 2) for duplicate section print the docstring to figure out where the problem is. * add warn test
1 parent a82926f commit 795afa8

File tree

2 files changed

+36
-2
lines changed

2 files changed

+36
-2
lines changed

numpydoc/docscrape.py

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,10 @@ def _is_at_section(self):
176176
return True
177177

178178
l2 = self._doc.peek(1).strip() # ---------- or ==========
179+
if len(l2) >= 3 and (set(l2) in ({'-'}, {'='}) ) and len(l2) != len(l1):
180+
snip = '\n'.join(self._doc._str[:2])+'...'
181+
self._error_location("potentially wrong underline length... \n%s \n%s in \n%s"\
182+
% (l1, l2, snip), error=False)
179183
return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1))
180184

181185
def _strip(self, doc):
@@ -387,8 +391,8 @@ def _parse(self):
387391
section = (s.capitalize() for s in section.split(' '))
388392
section = ' '.join(section)
389393
if self.get(section):
390-
self._error_location("The section %s appears twice"
391-
% section)
394+
self._error_location("The section %s appears twice in %s"
395+
% (section, '\n'.join(self._doc._str)))
392396

393397
if section in ('Parameters', 'Other Parameters', 'Attributes',
394398
'Methods'):

numpydoc/tests/test_validate.py

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -585,6 +585,22 @@ def directives_without_two_colons(self, first, second):
585585
"""
586586
pass
587587

588+
class WarnGenericFormat:
589+
"""
590+
Those contains things that _may_ be incorrect formatting.
591+
"""
592+
593+
def too_short_header_underline(self, a, b):
594+
"""
595+
The header line is too short.
596+
597+
Parameters
598+
------
599+
a, b : int
600+
Foo bar baz.
601+
"""
602+
pass
603+
588604

589605
class BadSummaries:
590606
def no_summary(self):
@@ -1037,6 +1053,20 @@ def test_bad_class(self, capsys):
10371053
assert isinstance(errors, list)
10381054
assert errors
10391055

1056+
@pytest.mark.parametrize(
1057+
"func",
1058+
[
1059+
"too_short_header_underline",
1060+
],
1061+
)
1062+
def test_bad_generic_functions(self, capsys, func):
1063+
with pytest.warns(UserWarning):
1064+
errors = validate_one(
1065+
self._import_path(klass="WarnGenericFormat", func=func) # noqa:F821
1066+
)
1067+
assert 'is too short' in w.msg
1068+
1069+
10401070
@pytest.mark.parametrize(
10411071
"func",
10421072
[

0 commit comments

Comments
 (0)