[Feature] Add validation for numpydoc

[K-Meech]

Is your feature request related to a problem? Please describe.
Currently, there are no checks for docstring style, meaning it is easy to introduce styles like reST erroneously.

Describe the solution you'd like
We could add validation of numpydoc via precommit with a pre-commit hook. Individual rules can be easily ignored in the pyproject.toml like so

[tool.numpydoc_validation]
checks = [
    "all",   # report on all checks, except the below
    "EX01",
    "SA01",
    "ES01",
]

[AlgoFoe]

Hi @adamltyson, I have opened a PR adding numpydoc validation as a pre-commit hook (#145). Would appreciate a look when you get a chance and happy to make any adjustments.

[thisisrick25]

Back when I wrote the api docs (brainglobe/brainglobe-atlasapi#584), we agreed to use ruff for linting/formatting due to its fast performance (brainglobe/brainglobe-atlasapi#581). As the codebase already uses ruff, I think it'll be best to take advantage of that.

@adamltyson @IgorTatarnikov @alessandrofelder

[AlgoFoe]

Hi @thisisrick25! ruff is definitely the right choice for linting/formatting, but it doesn’t replace numpydoc-validation. The latter performs semantic checks specific to NumPy-style docstrings (parameters, returns, section structure...) that ruff simply doesn’t implement.
In that sense, I would say they are complementary rather than interchangeable.

[thisisrick25]

tool.ruff.lint.pydocstyle.convention = "numpy" is a modern alternative for numpydoc_validation. Ruff’s D rules come directly from pydocstyle, and when set convention = "numpy", Ruff activates the NumPy-specific expectations for sections, formatting, structure, etc.

numpydoc_validation comes with very fine-grained semantic checks, which may require reformatting a large number of existing docstrs.

Eventually using either is fine, need @adamltyson @IgorTatarnikov opinion.

https://github.com/brainglobe/brainglobe-atlasapi/blob/main/pyproject.toml#L106-L116
https://github.com/brainglobe/brainglobe-atlasapi/pull/584/changes#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711

[AlgoFoe]

Thanks for clarifying @thisisrick25 ! Agreed, happy to follow what the maintainers prefer.

[adamltyson]

Thanks @thisisrick25. @AlgoFoe I think if ruff can be used instead, we'd rather stick with the tool we're already using.

[AlgoFoe]

I will close the PR #145 and let's stick with ruff.

[thisisrick25]

@AlgoFoe you dont need to close PR #145, just adopt ruff see brainglobe/brainglobe-atlasapi#584 for reference

[AlgoFoe]

Got it, I will update the PR to adopt ruff's NumPy docstring convention like you suggested and remove the numpydoc-validation hook.
And I may reach out here if I run into any issues.