search

numpy / numpydoc

Numpy's Sphinx extensions
https://numpydoc.readthedocs.io/
Other
297 stars 161 forks source link

Why should docstrings end with a blank line? #274

Open timokau opened 4 years ago

timokau commented 4 years ago

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.

jnothman commented 4 years ago

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.

timokau commented 4 years ago

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?

timokau commented 4 years ago

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.

rossbar commented 4 years ago

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).

charris commented 4 years ago

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.

e-gebes commented 3 years ago

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-paragraph command 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-paragraph command 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

charris commented 3 years ago

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.