Inconsistent formatting of parameter descriptions depending on whether they have one or multiple paragraphs

Subject: Inconsistent formatting of parameter descriptions depending on whether they have one or multiple paragraphs

Problem

Descriptions of parameters that have a single paragraph start on the same line as the parameter name and type, whereas descriptions of parameters that have multiple paragraphs start on a new line, creating an inconsistent layout.

Procedure to reproduce the problem

autodoc the following using a default environment.

def f(x, y):
    """
    :param x:
        The foo.
    :type x: int
    :param y: The other foo.

        But with two paragraphs.
    :type y: int
    """

Error logs / results

Expected results

Either consistently start the first line of the param description on the same line as the parameter name, or consistently start it on the line below. (The old behavior could be maintained as available using a config switch.)

Possibly better would be to stay on the same line if all param descriptions (for a given signature) are single-paragraph, and always start a new line as long as at least one param has multiple paragraphs.

Reproducible project / your project

• N/A

Environment info

• OS: Linux
• Python version: 3.6
• Sphinx version: 1.6.5