py-fill-paragraph: broken handling of paragraphs inside docstrings

[Matthew Willson]

py-fill-paragraph doesn't respect existing paragraph breaks when reflowing the docstring, e.g.

def foo(self)
    """One-line summary.

    Some other stuff which I don't want a paragraph break inserted into the middle of.

    And another para hjkdfgh fdjkg hfdjkg hdfjk ghdfk ghjkdf ghjkdf ghjdf ghjdkf k"""

=>

def foo(self)
    """One-line summary. Some other stuff which I don't want a paragraph

    break inserted into the middle of. And another para hjkdfgh fdjkg
    hfdjkg hdfjk ghdfk ghjkdf ghjkdf ghjdf ghjdkf k
    """

I feel it would be better if it didn't attempt to reflow the whole docstring, rather just reflow the particular paragraph within it which the point is positioned in.

While we're at it, I'm not sure that the attempts at automatically enforcing a one-line summary for the first paragraph of a docstring are really that useful. In cases where the first paragraph is too long to fit on a single line and comply with the PEP, trying to shoehorn it into that form by inserting a paragraph break in the middle of a sentence isn't really very useful and you have to undo it anyway in order to fix the problem. E.g.:

def foo():
    """Oops it looks like I got my one-line summary just a bit too long for one line"""

=>

def foo():
    """Oops it looks like I got my one-line summary just a bit too long

    for one line
    """

Not really very useful introducing that paragraph break in the middle of my sentence. Just reflow to

def foo():
    """Oops it looks like I got my one-line summary just a bit too long
    for one line
    """

and let me fix the "summary line too long" issue myself.

It would also be good if it could avoid mangling parameter descriptions like this:

def foo(self):
    """Summary line.

    Foo bar fhgdjkfd hgjfd hgjkfd ghjkdf ghjkdf hgjdf ghjkdf hgjdf hjgk dfhjkg dfhjkg dfhjkg fdhjkg hjfdkg

    Parameters
    ----------
    endog : array-like
        1-d endogenous response variable. The dependent variable.
    exog : array-like
        A nobs x k array where `nobs` is the number of observations and `k`
        is the number of regressors. An interecept is not included by default
        and should be added by the user. See
        `statsmodels.tools.add_constant`."""

=>

def foo(self):
    """Summary line. Foo bar fhgdjkfd hgjfd hgjkfd ghjkdf ghjkdf hgjdf

    ghjkdf hgjdf hjgk dfhjkg dfhjkg dfhjkg fdhjkg hjfdkg Parameters
    ---------- endog : array-like 1-d endogenous response variable. The
    dependent variable. exog : array-like A nobs x k array where `nobs`
    is the number of observations and `k` is the number of regressors.
    An interecept is not included by default and should be added by the
    user. See `statsmodels.tools.add_constant`.
    """

Failing that though, if I can at least choose to reflow individual paragraphs in the docstring and leave others intact, I can format these things manually while still being able to flow other paragraphs using M-q.

[Andreas Roehler (a-roehler)]

Should be done. In case first line is too long, either set py-docstring-style to nil or customize py-docstring-fill-column.