Decide on final docstring format

theochem / horton

HORTON: Helpful Open-source Research TOol for N-fermion systems

http://theochem.github.io/horton/

GNU General Public License v3.0

92 stars 40 forks source link

Decide on final docstring format #277

Open tovrstra opened 6 years ago

tovrstra commented 6 years ago

We can see examples of google and numpy docstrings here

http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html

matt-chan commented 6 years ago

So both the numpy and google docstrings have legacy formats where type are specified in the docstring and also modern ones where the type is in a 3.5-ish typehint.

I think the numpy style looks better. Also there's a smaller number of indents, which should be less trouble for programming.

tovrstra commented 6 years ago

Sounds good. I'm just adding reference for those who are new to this.

Type hinting: https://docs.python.org/3/library/typing.html
Pragmatic introduction: https://blog.jetbrains.com/pycharm/2015/11/python-3-5-type-hinting-in-pycharm-5/
A talk of Guido on the whyl: https://www.youtube.com/watch?v=2wDvzy6Hgxg

@matt-chan can you add links to a numpydoc spec with the type hinting?