[docs] use consistent style for docstrings

[anthrotype]

If I am not mistaken, I think @chrissimpkins has set up Sphinx to automatically format docstrings using the Google Style. Among other things, these include an Args list of parameters, Returns (or Yields for generators) for the return value, Raises for any exceptions, etc. More info here:

https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

In light of @simoncozens' latest efforts on documentation, it would be nice if we could agree and stick to one style for documenting code. The Google style seems to be among the most popular in the python community, and sphinx/RTD support this nicely so I'd propose we use that one.

WDYT?

[chrissimpkins]

If I am not mistaken, I think @chrissimpkins has set up Sphinx to automatically format docstrings using the Google Style.

correct!

[simoncozens]

Yeah, we should definitely use Google style. I'll do a second pass later fixing up all the docstrings, so please don't let this be a blocker for my incoming PRs. Some docs are better than no docs.

[anthrotype]

Agreed

[behdad]

Anyone see this happening?

[chrissimpkins]

I can take a look and begin updating the format.