Enforce linting of docstrings

[niksirbi]

Description

What is this PR

• [ ] Bug fix
• [x] 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
• [x] The code has been formatted with pre-commit

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

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

Additional details and impacted files

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

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[sonarcloud[bot]]

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 https://github.com/neuroinformatics-unit/datashuttle/issues/369