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.

Author: Carreau

numpydoc/docscrape.py

@@ -176,6 +176,10 @@ def _is_at_section(self):
             return True
 
         l2 = self._doc.peek(1).strip()  # ---------- or ==========
+        if len(l2) >= 3 and (set(l2) in ({'-'}, {'='}) ) and len(l2) != len(l1):
+            snip = '\n'.join(self._doc._str[:2])+'...'
+            self._error_location(f"potentially wrong underline length... \n{l1} \n{l2} in \n{snip}",
+                        error=False)
         return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1))
 
     def _strip(self, doc):
@@ -387,8 +391,8 @@ def _parse(self):
                 section = (s.capitalize() for s in section.split(' '))
                 section = ' '.join(section)
                 if self.get(section):
-                    self._error_location("The section %s appears twice"
-                                         % section)
+                    self._error_location("The section %s appears twice in  %s"
+                            % (section, '\n'.join(self._doc._str)))
 
             if section in ('Parameters', 'Other Parameters', 'Attributes',
                            'Methods'):