Support (detect?) missing blank line before Returns sections.

[Carreau]

It's not the fist time I come across this, but it looks like project regularly forget the blank line between Parameters and Return, leading to the Returns section being merged into Parameters.

That would likely need to update _read_to_next_section to use extra heuristics than read_to_next_empty_line,
Only checking for lines with ------, or ====== might not be sufficient as this also would match tracebacks.

Carreau/velin#14 for reference.

[keewis]

_parse_summary would also need to be changed:

Summary line.
Parameters
----------
param1 : int

As for filtering out tracebacks: we could either check for the section name (using NumpyDocString.sections.keys()) or check the line following the --- / === for the string "Traceback (most recent call last)" (which is in both the cpython and the ipython traceback)

[larsoner]

I'm -1 on fixing this in numpydoc -- this is invalid in plain RST, so I don't think we should support it. In other words, in plain RST this will render as a single header plus a long (ugly) section, not two:

First
-----
some content
Second
------
some more content

[rgommers]

Agreed with @larsoner, this is invalid and needs to be fixed in the docstring.