Allow line breaks in definition lists.

[terrencepreilly]

Rich Structured Text format requires a blank line after a definition list. However, darglint splits the arguments section in two if there is a blank line.

Possible solutions:

• Accept a configuration option for the docstring format, so that RST can be specified. This would allow us to parse the block quickly and accurately in both cases. However, this would require different splitting algorithms based on the format. We would also have to add an optional long description to the end of the arguments section, to handle the case where the arguments section doesn't continue after the line break.
• Assume, once the first section is encountered, that further sections will follow. Then add long description grammar to the end of the section grammars. This option would make the parser slightly lower (by increasing the grammar size), but would work correctly in most cases.
• Add the concept of block scope to the parser. So, later lines at the same indentation level would be assumed to be a continuation of the previous line at that same level. This would probably be the most natural solution, and would also fix having code examples in the argument descriptions. However, it would probably also be the most difficult to write. It may also make parallelization harder in the future. Currently, blocks are separated and treated independently, and so would easy to parallelize.

[terrencepreilly]

This is a follow-up to issue #28

[lvermue]

@terrencepreilly What is the status on this?

Currently docstrings cannot have multi-line returns, e.g.

:return: shape: (n, m), dtype: float
    Detailed description.

is not possible and raises DAR201. When the return docstring cannot be put into one line, the only way to mitigate this is to add a # noqa: DAR201.

[terrencepreilly]

I could be wrong, but I think what you're pointing out is a separate issue. I'll open a bug.