Add check for empty line between description and parameter list

[FabianNiehaus]

Currently, the following code passes validation:

"""
Construct the mappings with file line numbers included.

Overrides 'yaml.constructor.SafeConstructor.construct_mapping()'.
:param node: MappingNode object.
:param deep: Deep flag.
"""

However, once rendered, this is the result:

As you can see, the parameters were not rendered correctly.

Adding an empty line to the Docstring solves this issue:

"""
Construct the mappings with file line numbers included.

Overrides 'yaml.constructor.SafeConstructor.construct_mapping()'.

:param node: MappingNode object.
:param deep: Deep flag.
"""

Output:

It would be very helpful if flake8-rst-docstrings implemented a check for this.

[peterjc]

I can see why this would be nice, but currently this plugin does not invent any checks of its own - everything is done by docutils internally. You could try opening a feature request there for flagging this example with a warning?

https://sourceforge.net/p/docutils/feature-requests/

[FabianNiehaus]

I was not aware of that, my bad.

I opened a feature request on SourceForge: https://sourceforge.net/p/docutils/feature-requests/80/

[peterjc]

Quoting from the docutils discussion,

... example is valid rST but it is not what you intended. Because of the missing blank line, your docstring does not contain a field-list/param list but a large paragraph, so the rendering is technically correct (but not what you want).

Whether a check for "valid but not intended" input would be more helpful than in the way and at which stage it could be done, is open for discussion.

Closing as there is not going to be an error or warning from docutils for us to report via flake8.