As we write and update more docstrings, I think it would be helpful to specify what is expected and to do some checks in CI (and git pre-commit).

Like other libraries in the PyData ecosystem, I think we should rely heavily on the NumPy-style docstrings:

• https://numpydoc.readthedocs.io/en/latest/format.html

We can even use velin to help enforce this and identify common mistakes:

• https://github.com/Carreau/velin

Here's an example of velin being used as a git pre-commit:

• https://github.com/pydata/xarray/blob/main/.pre-commit-config.yaml
• Side note: let's check out other things that xarray does!

We could also look to align more closely to PEP 257 and its tooling:

• https://peps.python.org/pep-0257/
• https://github.com/PyCQA/pydocstyle

Pandas also has really good guidance for docstrings:

• https://pandas.pydata.org/docs/development/contributing_docstring.html
• Also worth checking out: https://github.com/pandas-dev/pandas/blob/main/.pre-commit-config.yaml

xref: #169 and #198