Adopt a style guide for docstrings

[EwoutH]

It might be useful to adopt a style guide for docstrings. Common ones:

• Strict PEP 257 Docstring Conventions
• The Google style guide
• The NumPy style guide
• The Sphinx docstring format

For example, the NumPy style guide maintains a white line before the last """, while the others do not.

[rht]

It looks like this can be linted with https://github.com/PyCQA/pydocstyle.

[rht]

Auto-formatter: https://github.com/PyCQA/docformatter

[rht]

My natural preference is without the extra line, but I'd want to know why NumPy, SciPy, and the scikits choose to have it. Their guideline doesn't say anything about it.

[Corvince]

Good idea. I would naturally prefer the nummy style guide, since we are part of the scientific python ecosystem.

The thing with the empty line before the triple quotes seems useless to me but shouldn't be a decisive factor imho, it is rather pointless to discuss about such a matter

[rht]

pandas and NetworkX don't have the extra line. Surprisingly, scikit-learn doesn't have it either.

[Corvince]

Also consider that guide lines are guide lines, not strict rules. The blank line doesn't seem important and there is no reason not to follow the numpy guide lines, but skip the last line. (as seen in linked packages by @rht )