Fix appearance of class docstrings, constructor methods, ...

[nyalldawson]

This PR results in a lot of improvements :smile:

It's directed at fixing this:

Where:

1. The constructors just get dumped as part of the class description, making the text confusing to read
2. The way the constructors just appear as plain text, not functions

Now:

Class description shows at the top of the page:

While constructors are nicely documented + formatted before the other methods:

It also fixes this issue, where the notes block format leaks into the table of contents:

Now it's correctly formatted: