Yes indeed. For those unfamiliar, here are (from the link) examples of the two docstring styles that Napoleon (a Sphinx extension) parses and renders. PyCharm, too, parses Numpy and Google docstrings and uses the information for tooltips, static analysis, etc.
Google style:
"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return True
NumPy style:
"""Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
"""
return True
Hmm, Google’s style + napoleon extension does seem quite good. I wonder if I should update my style guide. I suggested that you should just bite the bullet and use Sphinx style there due to the doc auto-gen benefits, but seems like this is best of both worlds.
Looks really nice! The ad-hoc informal type notation makes me wonder how it would look with real type annotations.
You wouldn’t necessarily have to adopt actual type checking (though my team at work has found mypy really handy) — but if you’re going to the effort of documenting every parameter and return value, might as well let the computer check that the docs are correct/up to date!
You shoud seriously look at the napoleon / google doc: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/
This is already implemented and supported standard.
Yes indeed. For those unfamiliar, here are (from the link) examples of the two docstring styles that Napoleon (a Sphinx extension) parses and renders. PyCharm, too, parses Numpy and Google docstrings and uses the information for tooltips, static analysis, etc.
Google style:
NumPy style:
Hmm, Google’s style + napoleon extension does seem quite good. I wonder if I should update my style guide. I suggested that you should just bite the bullet and use Sphinx style there due to the doc auto-gen benefits, but seems like this is best of both worlds.
Looks really nice! The ad-hoc informal type notation makes me wonder how it would look with real type annotations.
You wouldn’t necessarily have to adopt actual type checking (though my team at work has found mypy really handy) — but if you’re going to the effort of documenting every parameter and return value, might as well let the computer check that the docs are correct/up to date!