Validate public API docstrings using Ruff

[VeckoTheGecko]

By validate docstrings I mean:

• Check that the docstring format is being adhered to
• Check that all parameters in the function are available in the docstring
• Perhaps check something or other about the type information?

Ruff rules that might be of interest:

• pydoclint (DOC)
• pydocstyle (D)

Though note that these rules don't necessarily have feature parity with the original packages (e.g., pydoclint)

The goal isn't to enable all these rules and have 100% compliance - some of these rules are just a headache. Let's pick rules that help with our goals.

The docstrings should also focus on the public API of Parcels. The private API does not have to adhere to the numpy format of docstrings, and sometimes functions don't need docstrings at all since the code is self-documenting via good variable names and easy-to-follow code

[VeckoTheGecko]

Related conversation in the #maintainer channel in the Scientific Python Discord

Brigitta Sipőcz
I wonder if any of the projects use any docstring linter for numpydocs formatter docstrings? I am looking for something that is rather forgiving and am only intrested in picking up issues that would cause rendering issues (but for which sphinx may not complain, e.g. the whitespaces around : in parameter lists, etc.

lucas
i.e. the numpydoc linter is too strict for you?

Brigitta Sipőcz
I don't know, haven't used it yet 🙂

lucas
it is very strict 😅 but configurable. We use it in https://github.com/data-apis/array-api-extra/blob/main/pyproject.toml#L92

Brigitta Sipőcz
the reporting it provides is a bit weird looking, but I suppose I could work with it.
someone else suggested pydoclint

Brigitta Sipőcz
OK, so I looked at the actual output, it seems to be super strict (or we have horrible docs -- totally plausible); 7600 lines of complaints 😱

lucas
some of the defaults are very questionable, we still have a very strict config but this might reduce the number of complaints quite a bit:

[tool.numpydoc_validation]
checks = [
  "all", # report on all checks, except the below
  "EX01", # most docstrings do not need an example
  "SA01", # data-apis/array-api-extra#87
  "ES01", # most docstrings do not need an extended summary
]
exclude = [ # don't report on objects that match any of these regex
  '.*test_*',
]

you can also look at our inline numpydoc: ignore statements to see the kind of things you might want to ignore globally

Brigitta Sipőcz
Thank you so much!

[reint-fischer]

As of #2395 we have set up rules for the files that contain core public classes and functions:

Parcels/pyproject.toml

Lines 128 to 137 in d4bbfc2

	[tool.ruff.lint.per-file-ignores]
	# Ignore docstring rules everywhere except for the stable files (particleset.py, interpolators.py).
	"!src/parcels/{_core/basegrid,_core/field,_core/fieldset,_core/kernel,_core/particle,_core/particlefile,_core/particleset,_core/uxgrid,_core/xgrid,kernels/advection,kernels/advectiondiffusion,interpolators}.py" = [
	# Missing docstring in public class
	"D101",
	# Missing docstring in public method
	"D102",
	# Missing docstring in public function
	"D103",
	]

For now, these only check for the presence of a docstring. We might want to expand these rules to include the following:

• Must include Parameters
• Must include Returns