Add numpydoc validation as a pre-commit hook

[AlgoFoe]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

• There are currently no automated checks enforcing docstring style, which makes it easy to introduce non-numpydoc-compliant docstrings.

What does this PR do?

• It adds numpydoc-validation as a pre-commit hook and enables automated validation of docstrings against the numpydoc standard.

References

• Related feature request: [Feature] Add validation for numpydoc #56

How has this PR been tested?

• Tested locally by running pre-commit run numpydoc-validation --all-files and confirming that the hook executes and reports existing docstring issues.

Is this a breaking change?

• No.

Does this PR require an update to the documentation?

• No.

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality (unit & integration)
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[AlgoFoe]

Note: the numpydoc pre-commit hook currently reports existing docstring and encoding issues. This PR only introduces the validation hook and it doesn’t attempt to fix existing violations to keep the scope focused.

[AlgoFoe]

Note: the numpydoc pre-commit hook currently reports existing docstring and encoding issues. This PR only introduces the validation hook and it doesn’t attempt to fix existing violations to keep the scope focused.

The pre-commit failures are from the new numpydoc-validation flagging existing issues, so should I fix them here or leave them for a follow-up PR.

[adamltyson]

The pre-commit failures are from the new numpydoc-validation flagging existing issues, so should I fix them here or leave them for a follow-up PR.

If you could fix them here, that would be great. I'd rather not merge something that will make the test suite fail.

If you see any other BrainGlobe repos that this could be added to (without a huge reformatting of existing docstrings), let us know. In theory all BG repos should use the numpy standard, but we haven't really spend any time standardising this.

[AlgoFoe]

The pre-commit failures are from the new numpydoc-validation flagging existing issues, so should I fix them here or leave them for a follow-up PR.

If you could fix them here, that would be great. I'd rather not merge something that will make the test suite fail.

If you see any other BrainGlobe repos that this could be added to (without a huge reformatting of existing docstrings), let us know. In theory all BG repos should use the numpy standard, but we haven't really spend any time standardising this.

Thanks for clarifying, I will fix the existing docstring issues in this PR so the test suite passes cleanly, and push an update shortly.
And I will also look for other bg repos where this could be added and let you know if I find any.

[adamltyson]

Hi @AlgoFoe, as dicussed in the developer meeting today, it would be great if we could converge on a single configuration here and in the atlas API. Ideally something that enforces as much standardisation as possible, without being too onerous to adopt here, or in other BrainGlobe repos.

[AlgoFoe]

Thanks @adamltyson, sounds good. I am aligning the configuration with the atlas API and adding minimal docstrings to move toward a single shared setup.