Investigate docstring formatting check options #620
Description
Summary
We primarily use the Google style for docstrings. However, this is not currently uniform nor are our docstring uniform in what information they present. Before blindly activating a whole bunch of checks, it would be useful to isolate which checks are the most useful for us & perform an analysis of the impact.
Options:
- https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
- https://docs.astral.sh/ruff/rules/#pydoclint-doc
- https://docs.astral.sh/ruff/rules/#pydocstyle-d
Requirements
- Any checks we activate for this should affect newly added or modified code, but it should not penalize a developer for past and untouched issues.
- Since this is the first time docstrings are discussed in this manner, the effort should be focused on the biggest win first & not all the nice things we could do.
- It should be established if there are preferences in the team regarding docstring usage, like only when I think it's useful to have or always or whatever the in-betweens are.
To Dos
- Add to the python-toolbox about what our documentation style preferences are (i.e. Google style & when/where)
- Survey team to get an idea of the documentation preferences
- Create a table of available options & highlight which would be useful for us
- Consider where it would be useful to have activated -> either as a CI nox session check or rather visualized in Sonar
- Draft up a proposal and pitch it to interested parties within our team