Docstrings are formatted badly.

[nikfilippas]

Most docstrings do not adhere to any formatting standard. As a result of this

1. they are hard to read directly from the source code as they are very cluttered
2. every developer uses their own style so there's a bunch of different styles currently implemented
3. they don't integrate well with any IDE.

For example, this docstring: shows like this in the IDE

We should adopt a developer's style guide. Copying numpy's style guide is a very good choice. Look what difference it makes in the source code's readability and the IDE:

[damonge]

I'd like to give the docs a full sweep once we merge everything that goes right before v2 and then right before we publish v3

[nikfilippas]

yeah me too, I've already started doing that in my dev branches

[damonge]

OK, but don't waste too much time on that. We will need to do a final exhaustive sweep anyway.