Docstring linting

[shadeMe]

Tasks

Beta Give feedback

1. Come up with a sane configuration for linting docstrings using pydocstyle.
2. Apply the configuration to the codebase and monitor with CI doc: adding docstring linting based on ruff #7463

[davidsbatista]

pydocstyle is currently archived and deprecate in favor of ruff: PyCQA/pydocstyle#658

I will look into ruff

[davidsbatista]

ruff supported rules for pydocstyle

https://docs.astral.sh/ruff/rules/#pydocstyle-d

[davidsbatista]

one downside is that every single public functions needs to have a docstring, but in some cases one doesn't want to have that enforced, e.g: small utility functions

this could be avoided with the pylint parameter: docstring-min-length which is still yet to be implemented in ruff astral-sh/ruff#5860

[davidsbatista]

I would like to add the rules below from pydocstyle which ruff supports, and go in line with the big docstring refactoring with did a while ago:

• "D102", # Missing docstring in public method
• "D103", # Missing docstring in public function
• "D205", # 1 blank line required between summary line and description
• "D417", # undocumented-parameter
• "D419", # undocumented-returns

but this will force us to add docstrings to every single function, in summary:

• D103 Missing docstring in public function (3 instances)
• D102 Missing docstring in public method (158 instances)
• D205 1 blank line required between summary line and description (182 instances)

Alternatively we could go with pylint, which is less expressive, as far as I understood only has these 3 rules:

• missing-module-docstring
• missing-class-docstring
• missing-function-docstring

but allows to control which functions/methods need a docstring based on the number of lines:

• docstring-min-length=10
• missing-function-docstring

using this config would require for now only 17 changes.

My proposal: use pylint as described and keep an eye on astral-sh/ruff#5860, when it's implemented we can swtich to ruff