Enforce linting of docstrings

[niksirbi]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

We recently implemented a linting/code formatting overhaul, relying on ruff #156.
However, we are still missing linting/formatting for docstrings. Would be nice to have them all formatted in a uniform way.

What does this PR do?
It adds the "D" (pydocstyle) ruleset to the ruff config.
That enforces a bunch of rules on docstring formatting, and most problems are auto-fixed.
However, I had to fix lots of issues manually, because many of our existing docstrings were non-compliant.

The rules that necessitated most manual work were the ones stipulating that docstrings should start with a one-line short description ending in a period, optionally followed by a longer description (separated from the one-liner by 1 blank line), e.g.:

def foo(bar):
    """Perform some function (has to fit in one line).
    
    Here is the longer description which can extend over
    multiple lines.
    """

This is a bit restrictive and I had to rewrite a bunch of docstrings accordingly, but I like the consistent result we end up with.
Going forward this should be much less work, because we'll get immediate feedback on this via pre-commit, so no additional inconsistencies should creep in.

I relaxed the rules quite a bit for the tests folder, because those docstrings are not public-facing.

The relevant configuration changes are to be found in pyproject.toml. All the other diffs have to do with fixing issues encountered during pre-commit run --all-files.

How has this PR been tested?

Visually checked the locally rendered sphinx API docs.

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
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.66%. Comparing base (6702100) to head (00f8ab6).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #165   +/-   ##
=======================================
  Coverage   99.66%   99.66%           
=======================================
  Files          10       10           
  Lines         605      605           
=======================================
  Hits          603      603           
  Misses          2        2           

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

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

[niksirbi]

@JoeZiminski this PR implements docstring litning, in case you want to do the same in datashuttle neuroinformatics-unit/datashuttle#369