DOC: remove usage of code-block directive in docstrings + fix some warnings
Some docs things:
- remove remaining use of `code-block`, closes #3430 (@y-p, I think that were the last ones, so now it can be really closed)
- fix some headers to avoid useless warnings during doc build (if the line under the header is not as long as the header itself, sphinx complains about it although it renders fine)

"markup code snippets as such" somehow became "remove usage of code-block in docstrings"
somewhere along the way, but as long as it's consistent across the package it's fine by me.

merge away.
 @y-p yeah .. it's indeed maybe not exactly the same as the issue (but it is also more difficult to search the code snippets that are not highlighted as code), but I don't mean remove code blocks, but the literal use of `code-block` and replace with eg `::` as the `code-block` is redundant.
