KipCrossing / geotiff

A noGDAL tool for reading and writing geotiff files
GNU Lesser General Public License v2.1
213 stars 23 forks source link

Use a docstring convention #49

Closed Zeitsperre closed 1 year ago

Zeitsperre commented 2 years ago

@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.

KipCrossing commented 2 years ago

@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.