In #48, I've staged the possibility of a potential git commit hook that runs pydocstyle. This is a linter that helps with ensuring that documentation of functions is properly parsed and rendered in documentation-building engines (like sphinx).
There are several docstring style standards that are possible:
The major benefit of this is to help build interactive and automatically-built documentation, but even with a small project such as geotiff, there will be significant changes to the docstrings. Once a convention is agreed on, all changes shouldn't take too much effort.
@Zeitsperre cool! For the docblocs so far, I've just been using the Google standard (I do this via vscodes autoDocstring) extension. So let's do google.
@KipCrossing
In #48, I've staged the possibility of a potential git commit hook that runs pydocstyle. This is a linter that helps with ensuring that documentation of functions is properly parsed and rendered in documentation-building engines (like
sphinx
).There are several docstring style standards that are possible:
I'm partial to numpy-style, but anything that renders well would work.
Pydocstyle also offers suggestions on content and grammar style (see: http://www.pydocstyle.org/en/stable/error_codes.html), but these can be selectively ignored as needed.
The major benefit of this is to help build interactive and automatically-built documentation, but even with a small project such as
geotiff
, there will be significant changes to the docstrings. Once a convention is agreed on, all changes shouldn't take too much effort.