Use a Single Python Code Documentation Style

[cannin]

It looks like Google-style

https://github.com/Bioprotocols/paml/blob/802b65dc1628c53b149af47a525af8828ce516f5/paml/__init__.py#L258

and reStructuredText-style

https://github.com/Bioprotocols/paml/blob/802b65dc1628c53b149af47a525af8828ce516f5/paml/__init__.py#L72

are being used together in the code

[rpgoldman]

I have a pretty strong preference for Numpy style, which is readable when run through Sphinx but also readable in an editor or in python’s help. Google style is probably ok too. ReST style is ugly and cumbersome

[cannin]

@rpgoldman I have no strong preference other than consistency so that an API documentation generator will not have issues

[rpgoldman]

Here’s a good comparison of the three most prominent styles: https://queirozf.com/entries/python-docstrings-reference-examples

ReST/Sphinx style in my opinion is very hard to read on the screen until after it’s formatted by Sphinx, which means it’s not good with help() .

I prefer Numpy over Google, but that’s just because I’m used to it. Either would, IMO, be fine for PAML

[rpgoldman]

I have no direct experience with pydocstyle but perhaps it could be incorporated into our automated test framework, if we can choose a style.

I’ll experiment with it on some of my other projects.