Docstring conventions are in PEP-257 with much more detail than PEP-8.
However, docstrings seem to be far more personal than other areas of code. Different projects will have their own standard.
I tend to always include docstrings, because they tend to demonstrate how to use the function and what it does very quickly.
I prefer to keep things consistent, regardless of the length of the string. I like how to code looks when indentation and spacing are consistent. That means, I use:
def sq(n):
"""
Return the square of n.
"""
return n * n
Over:
def sq(n):
"""Returns the square of n."""
return n * n
And tend to leave off commenting on the first line in longer docstrings:
def sq(n):
"""
Return the square of n, accepting all numeric types:
>>> sq(10)
100
>>> sq(10.434)
108.86835599999999
Raises a TypeError when input is invalid:
>>> sq(4*'435')
Traceback (most recent call last):
...
TypeError: can't multiply sequence by non-int of type 'str'
"""
return n*n
Meaning I find docstrings that start like this to be messy.
def sq(n):
"""Return the squared result.
...