Point to alternative formats for docstrings

[jiffyclub]

The default Sphinx style for docstrings is hard to remember and not especially legible (unless rendered). Multiple friendlier alternatives exist, including the popular NumPy and Google formats, both of which can be rendered by the Sphinx Napoleon extension that is included with Sphinx.

[amontalenti]

@jiffyclub This is an interesting point, thank you for opening this PR. It's a good opportunity for me to explore the alternatives, which I didn't really know much about before you raised this issue. Give me a day or two to review them and maybe I'll change the recommendation altogether. Indeed, the PEP for docstrings only says to use reST and doesn't endorse a specific flavor of markup, I don't think, so some research here would probably be worth it.

[jiffyclub]

The first example of this I knew of was numpydoc. Scientific programmers are often interacting directly with docstrings as they are written in the source code (thanks to IPython, or because they are using shared lab code), and the default Sphinx style is not conducive to that situation. But Sphinx is extensible so someone came up with an alternative that could be both legible in source code and rendered by Sphinx.

More recently Google published their own Python Style Guide with their own recommendations for docstring style and that's been implemented as a Sphinx extension as well.

[nedbat]

+1 to napoleon style.

[amontalenti]

@nedbat So that's a vote for Google style, right?

[nedbat]

Yes, I prefer Google to Numpy, though either is much better than the :param: junk.

[amontalenti]

@nedbat It's a fair point. As I mentioned, I didn't even know about Google's docstring style and its Sphinx support until this issue was opened. Looking forward to evaluating and revising the recommendation.

[j6k4m8]

A huge vote for this. In my opinion, (Google ≈ numpy) >> :param:, and even then, Google's slightly better than numpy.

[ariddell]

Numpy's style is supported by Sphinx since 1.3: http://sphinx-doc.org/latest/ext/napoleon.html

[amontalenti]

For users of the Google style on this thread, do you end up using the Optional[int] and Optional[bool] types as suggested in the docs for optional arguments? I find this a little clunky, though I realize that this is syntax taken directly from the typing module in Python 3.

When I tried to port a real module from Sphinx style to Google, I failed to see why the Google style has such strong proponents. Is it merely the lack of "special" markup for :param: and similar directives?

If anything, this decision of which docstring "style" (above reST markup) to use strikes me as one for my "Six of One, Half a Dozen of the Other" section. I should say that at a minimum, you should pick a Sphinx-compatible docstring style, and point to the ones currently available.

On Sphinx vs Google, they seem about equally concise and readable to me.

(Examples of Google style for reference: http://www.sphinx-doc.org/en/stable/ext/example_google.html)

[amontalenti]

Also learned something I never knew about the Sphinx style: you can specify types in :param:, e.g.

    :param url: URL for the new request.
    :type url: str

Can be rewritten:

    :param str url: URL for the new request.

[nedbat]

For me, the advantage of Google style is that it aims for the original wiki philosophy: make the "markup" unobtrusive, and feel natural when reading the source. This seems like a reasonable ascii description of an argument to me:

Arguments:
    url (str): URL for the new request.

This seems cluttered with punctuation that is clearly there just for the convenience of a parser some place:

:param str url: URL for the new request.

The colon after "url" parses as introducing the rest of the sentence, but then what is :param str? It's an awkward combination of English and psuedo-markup. Much better to use Google style, where the markup is invisible to the reader.

[jiffyclub]

Writability and readability in the source code are my reasons for disliking the default style. When reading :param str url: which of those is the type and which the name of the string? There's no separation. And it's difficult to remember the order when writing it too.

Then look at a whole block of these:

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage

Which of those is a parameter description and which is a type annotation? There's no clear separation between the parameter descriptions and the return description. The type annotation for the return value is for some reason different. This is clearly not meant for humans to read.

[jiffyclub]

I disagree heartily that the default Sphinx style has equivalent readability to NumPy or Google styles, especially to someone not steeped in the Sphinx style. And I figure if you want people to actually write docstrings, the easier they are to read and write the better.

[amontalenti]

@nedbat @jiffyclub Good points. I see where you're coming from, and I agree that it's best when the markup gets out of the way. Indeed, the purpose of docstrings in Python is that they should be displayable in e.g. help() from an interactive prompt, so the better the content-to-markup ratio, the more in-line with Python's vision for docstrings, IMO.

After looking a bit more closely at Google style and napoleon's support for it, I think I'm starting to come around. Sometime soon I'll open a PR revising the docstring and see how it looks/compares. I suspect it'll look better.

On another note, it would be great if someone wrote a definitive guide to the Google style of docstring. The links on this thread include some examples but a true "reference" to the style would be a good community contribution.

[amontalenti]

(this is probably the closest thing to an "official" reference, buried inside the Google style guide for Python -- a guide which I actually disagree with for a lot of its other recommendations! :))

[jiffyclub]

Yeah the NumPy style has a nice reference at https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt. The Google one def leaves much to be desired and I end up referring to http://www.sphinx-doc.org/en/stable/ext/example_google.html#example-google.

[amontalenti]

Scanning that, numpy definitely wins on the point of having plenty of meta-documentation and extensive examples! Thanks for sharing, @jiffyclub.

[jiffyclub]

Dunno if it got updated or I didn't notice before, but according to http://www.sphinx-doc.org/en/stable/ext/example_google.html#example-google you can use a (int, optional) syntax for optional arguments in the Google style.

[ariddell]

Ignore my previous comment (implicitly) in favor of Numpy. I had thought that Sphinx did not support Google style. It turns out that Sphinx does.

Google and Numpy style are both supported by Sphinx. Khan Academy recommends Google style. It would be great to encourage use of either Google (my preference) or Numpy style by using it in the provided example.

[cdcme]

+1 for merging this. I use Google style and definitely prefer it to RST.

[ryan-feeley]

Good discussion! Late to this party, but since this shows up in google searches I thought I'd throw in at least one good word for Numpy style. I find Numpy works a bit better when you get into scientific computing. For better or worse, this type of code tends towards many parameters, and parameters that require more than a few words of explanation.

In this situation, the extra vertical space of numpy style is a marginal difference, and there is less visual clutter when you scan the docstring since a parameter description that runs beyond a single line doesn't require another level of indent.