Fix numpy docstring example parsing

[kesmit13]

The numpy example parsing didn't seem to work the way numpy examples are formatted in the real-world. The assumption is that they look like this:

Examples
-----------
>>> print('hi')        <== code snippet
hi                            <== description

However, the correct interpretation is:

Examples
-----------
>>> print('hi')          <== code snippet
hi                              <== output of code snippet

If descriptions are used, they go before the snippet:

Examples
----------
Print the word 'hi':

>>> print('hi')
hi

It is also possible to have continuation marks after the initial Python prompt:

Examples
-----------
Print the word 'hi' 5 times:

>>> for i in range(5):
...    print('hi')
hi
hi
hi
hi
hi

The code in this PR changes the way that numpy examples are parsed to allow for these changes, so it is a breaking change.

[rr-]

Thank you for the PR. A couple of notes:

• Can we update the tests to cover the added functionality?
• Let's update the changelog to include this change.
• Let's rebase with the newest changes and fix the styling issues.