[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.

[rr-]

Thanks a lot for this, and sorry it sat for so long. You were right: the output under a >>> line is the output of that snippet, not a description of it.

Main now reads examples the way doctest does, which landed in #167. A snippet keeps its >>> lines, their ... continuations and the expected output together, the text before a snippet is its description, and text after the last snippet becomes an example with no snippet. This works the same for Numpydoc and Google, and compose writes it back the same way.

Since that change covers what this PR does, I'm closing it. Your write-up of how real Numpydoc examples look was a big help in getting this right. Thanks again!