numpy
Why should docstrings end with a blank line?
The example points out that
If your docstring does extend over multiple lines, the closing three quotation marks must be on a line by itself, preferably preceded by a blank line.
I'm curious if there is any reason for that preference or if it is just picked arbitrarily. It seems a bit unintuitive to me to put that blank line into the docstring. If you want visual separation to the implementation, putting it after the docstring would seem better.
Note that I'm not trying to start a style discussion, I'm just looking for clarification if there's any particular reason for the suggestion. I hope this is the right place to put this sort of question. CC @jnothman, who added the example in e71411db7518fc6c92bfdbb1ca48699521f1b72d.
I took most of that change from the numpy repository rather than inventing it.
I agree that I can't see why there should be a blank line there.
Okay, thanks for the clarification. We'll probably leave out the blank line in our project's numpydoc flavor then.
I do think it would be good if numpydoc had an explicit opinion on that though. I'd prefer if it was "no blank line", but any fixed guideline would be good. Should I close this issue or keep it open for further discussion/opinions?
I did some more git-history archeology, and it looks like the actual first mention was by @jarrodmillman in https://github.com/numpy/numpy/commit/76ab788ef20cfae3417b3d9a8513d6df13acd839 back in 2007.
Just to clarify, the referenced suggestion seems to apply to module docstrings.
It does seem that this is more of a style choice than something that is part of the numpydoc specification. For example, test_renders_module_docstring in numpydoc/tests/tests_main.py passes when parsing the numpydoc/__init__.py module docstring which does not have the blank line before the closing """.
There are other cases where numpydoc appears to make style suggestions that are not really part of the specification itself (see #241 and #244 for example). It might be useful to try to separate out style suggestions from things that are truly part of the numpydoc specification (i.e. rules that will cause docstring parsing to fail if they are violated).
I've always used a blank line at the end of docstrings because it provides better separation from the code. Whether that is recommended somewhere I don't know.
The clause
preferably preceded by a blank line
seems to be copied from PEP 8 back then when the NumPy docstring guide was introduced. The clause is not part of PEP 8 as of today. According to the Wayback Machine (archive.org) it was removed in 2014.
PEP 8 / PEP 257, June 2006:
PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, and preferably preceded by a blank line, e.g.:
The BDFL [3] recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs'
fill-paragraphcommand can be used on it.
https://web.archive.org/web/20060610022424/http://www.python.org/dev/peps/pep-0008/ (section "Documentation Strings") https://web.archive.org/web/20060621215239/http://www.python.org/dev/peps/pep-0257/#multi-line-docstrings
August 2014 (consistent with today's version):
PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, e.g.:
Unless the entire docstring fits on a line, place the closing quotes on a line by themselves. This way, Emacs'
fill-paragraphcommand can be used on it.
https://web.archive.org/web/20140819083127/http://legacy.python.org/dev/peps/pep-0008/#documentation-strings https://web.archive.org/web/20140816085730/http://legacy.python.org/dev/peps/pep-0257/#multi-line-docstrings
From what has changed in the PEPs it seems that Emacs' fill-paragraph got improved and the blank line was not necessary anymore (this is speculation), and so they adapted the PEPs accordingly.
So, the clause is in the example of the NumPy docstring guide for historic reasons. The blank line is not needed for numpydoc to work, apparently also not for fill-paragraph (anymore), and is not part of PEP 8 (anymore).
You might want to remove the hint and the blank lines from the example file, and subsequently maybe also from the NumPy code base.
See also the post from "endolith" on stackoverflow:
Emacs, really? Everyone should do weird things to cater to the idiosyncrasies of a particular command in a particular editing tool?
https://stackoverflow.com/questions/3955903/what-pep-8-guidelines-do-you-ignore-and-which-ones-do-you-stick-to/15303749#15303749
I didn't know it was part of a pep, but I prefer it because it looks nicer and effectively separates the docstring from the code.