DOC: Function signatures look untidy

[d-v-b]

Describe the issue linked to the documentation

The function signatures in our docs are hard to read. See this example.

Suggested fix for documentation

Long function signatures should be easy to read. I have experience with the mkdocstrings package for mkdocs, that produces much more readable function signatures. See this example from pydantic:

It's long, but much more readable.