Numpy style docstrings?

[ColCarroll]

pydocstyle merged in checking for numpy style docstrings this year. I'm intending to open a PR to get pymc3/step_methods/hmc, which currently has 45 violations, to conform to this, which might help get a discussion about doing that for the rest of the project, which has 1,381 violations.

The benefits are that it will allow us to use more of the documentation tools being built for the rest of the python science stack. The downsids are that it is one more hurdle to jump on PRs, and it can discourage quick iteration. There's a half-step I sort of like of enabling it for specific directories.

pydocstyle --convention=numpy pymc3/step_methods/hmc/ 

To see current problems!

[ColCarroll]

See also https://discourse.pymc.io/t/issue-numpy-style-docstrings/151

[ColCarroll]

Note:
This won't enforce that every argument is documented, or every return value. However, see scikit-learn/scikit-learn#9206, which looks to be on the verge of merging. That could be an interesting followup!

[junpenglao]

This is a good idea. Also I suppose lots of docstrings might be quite similar so it might not be as difficult as it sounds (still difficult with 1381 violations tho...)
We should put this into our Docathon goal.

[ColCarroll]

Closing since I do not think this is pressing, but it sounds like this is generally welcome if contributors want to update some documentation (doesn't have to be the whole project)!