[VeckoTheGecko]

Description

This PR only introduces tooling and formatting changes.

Checklist

• Closes Add pre-commit hook for documentation code formatting #2828
• Tests added
• This PR targets the correct branch (main for normal development, v3-support for v3 support)

AI Disclosure

• This PR contains AI-generated content.
  • I have tested any AI-generated content in my PR.
  • I take responsibility for any AI-generated content in my PR.
  • Describe how you used it (e.g., by pasting your prompt): doc fixes

[erikvansebille]

Thanks for the setup. Very nice fixes to the documentation code. I have only one (small) comment below

[erikvansebille]

This is the only change I don't really like. Is it really necessary that functions are surrounded by two white lines? Is there a way to ignore this rule? Or better to keep the full ruleset? It's not a dealbreaker if we keep this rule too...

[VeckoTheGecko]

https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#empty-lines

It will also insert proper spacing before and after function definitions. It’s one line before and after inner functions and two lines before and after module-level functions and classes

Black's tagline is "The uncompromising Python code formatter". Which is great, since they're no rules to configure! But there's the downside of there being no rules to configure.

Just a note: Formatting and linting are different. Formatting in the community has pretty much settled on Black and Ruff formatting (where Ruff is actually just a Rust implementation of Black), where there's very limited customisation (e.g, "quote style" vs 'quote style', and line lengths for wrapping). Linting is basically everything else, and result in physical changes to the Python AST (and allows you to pick rules etc. ).