Automate check of docstrings

[santisoler]

Description:

Since we are already using the numpydoc style in our docstrings, it would be nice if we automate the process of checking that they are properly written.

This could be done in the past using pydocstyle (and the flake8-docstrings plugin). But pydocstyle has been deprecated, and they recommend using ruff instead.

ruff is not only checking docstrings, but a whole linter (kind of an alternative to flake8). I think it would be nice to have this feature, but that would require us to discuss a little bit about depending on ruff.

Related to #149. We should tackle this after we merge #149.

Update 2024-05-14

We can use numpydoc itself to lint the docstrings for errors: https://numpydoc.readthedocs.io/en/stable/validation.html

Since numpydoc v0.18 it will be possible to call numpydoc from the terminal: https://numpydoc.readthedocs.io/en/latest/validation.html

Apply to:

• boule
• harmonica
• pooch
• verde
• ensaio
• choclo

Further instructions:

• Start by opening Pull Requests on each repository listed above.
• Optionally, we can open Issues on each repository if further discussion specific to that repository is needed.
• Mention this Issue on every Issue or Pull Request opened on each opened: Related to fatiando/community#XX
• Check-off the repository on the list above once the Pull Request is merged.
• Close this issue when all items are checked-off.

We want your help!

We know that maintenance tasks are very demanding, so we don't expect a single person to tackle this issue by themselves. Any help is very welcomed, so please comment below that you want to take care of the changes on any repository and we will assign it to you.