Add ruff docstring linting and fix issues

[MarcSkovMadsen]

Continues from #977.

This PR adds ruff docstring tests and cleans up.

More than 2200 docstring errors are identified by ruff. This will significantly change the wording and styling of the docstrings.

For example by adhering to

• https://docs.astral.sh/ruff/rules/non-imperative-mood/
• https://docs.astral.sh/ruff/rules/blank-line-after-summary/
• https://docs.astral.sh/ruff/rules/undocumented-public-function/
• https://docs.astral.sh/ruff/rules/ends-in-period/

Please note. I've added a little bit of ruff docstring configuration to pyproject.toml. Should be aligned with #978.

[MarcSkovMadsen]

I've made some example fixes for errors identified by Ruff. I will ask for a quick, preliminary review because it will be a large amount of work to clean up 2200 errors.

Are we OK with a change like this?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 87.25%. Comparing base (71e8e47) to head (938d6a0).
Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #979      +/-   ##
==========================================
- Coverage   87.26%   87.25%   -0.02%     
==========================================
  Files           9        9              
  Lines        4948     4951       +3     
==========================================
+ Hits         4318     4320       +2     
- Misses        630      631       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[maximlt]

2200 errors

Woo! I'd suggest ignoring some rules to avoid having so many errors. For instance, if it complains about public API not having a docstring, let's ignore that for now, as adding docstrings everywhere will be a lot of work. Other than that, I'm fine in principle with this approach.

Oh and let's perhaps update the PR title not to say docstring tests but docstring linting as I don't think this is running any doctest, right?

[MarcSkovMadsen]

I do plan to add the missing docstrings on public functions.

It's what I want to achieve: that there is documentation.

[maximlt]

I do plan to add the missing docstrings on public functions.

Nice! But I'd say it shouldn't be done in this PR, the goal of this PR should be to set up ruff linting for docstrings and ignore rules that make it fail. Then, you can gradually add docstrings and fix them in future PRs. If you do everything in a single PR, there's a big chance it will stall, as it's a lot of work to review.

[MarcSkovMadsen]

I do plan to add the missing docstrings on public functions.

Nice! But I'd say it shouldn't be done in this PR, the goal of this PR should be to set up ruff linting for docstrings and ignore rules that make it fail. Then, you can gradually add docstrings and fix them in future PRs. If you do everything in a single PR, there's a big chance it will stall, as it's a lot of work to review.

The problem is that I can't set ruff up for any docstring rule. It will fail no matter which rule is added.

Ok I will add docstring rules one at a time if that is better for you.

[maximlt]

Ok I will add docstring rules one at a time if that is better for you.

I'm not necessarily saying one rule at a time. It's just I'd like to avoid having to review all the docstrings of the complete API at once, as it's a lot, and I'm quite sure there are a few traps along the way that could slow you down or even block you entirely if done in one PR, while if you iterate we can be much more efficient and release improvements quickly. Some of the traps I think about:

• I don't know to which extent the public/private separation of the API is correct, there may be some public objects (in the sense they don't start with _) that we don't want to expose to users more, so we could make a case for not adding a docstring to these ones.
• I've been wondering for a long time how to add docstrings to the Parameters. They all have a pretty long list of common keywords and also some custom ones. For the common ones (e.g. constant, readonly, label), I don't think there's a way in Python to statically inherit a keyword docstring definition? Is the only solution available to copy/paste these definitions for all the Parameters? If so, how do we maintain it so they stay in sync? Does that affect import times? Could/should they live in a .pyi file, and if so, what are the pros/cons?

[MarcSkovMadsen]

Based on feedback I will close this one and add one micro rule at a time.