Preferred docstring style

pytest uses various docstring styles, which also leaks to the documentation, and I’m starting to develop an OCD from this!

I propose we use this style:

def func(arg: ArgType) -> Foo:
    """Do important stuff.

    More detailed info here, in separate paragraphs from the subject line.

    Use proper sentences -- start sentences with capital letters and end with periods.

    Can include annotated documentation:

    :param ArgType arg: an argument which determines stuff.
    :returns the result.
    :rtype Foo
    :raises ValueError
    """

After we agree on a style I’ll make a sweep over the code (possibly gradual) to update to it.

[aklajnert]

@nicoddemus

I agree with everything in the style except duplicating the type information when it we already have native type annotation, because Sphinx picks those up correctly.

From I remember in some previous PR sphinx doesn’t linkify the type in an annotation, but I’ll check again. Might not be worth the duplication even if it doesn’t.

IIRC I was using sphinx-autodoc-typehints extension to show the annotations correctly. Not sure if it will fit here, but might be worth checking.

[nicoddemus]

1. I usually prefer imperative too, but don’t have strong feelings either.
2. Capital letter and period. This is important when you need more than one phrase to explain a parameter.
3. Also prefer the last one: easier to maintain.
4. Agreed, same: aim for around 80 chars.