[rr-]

Numpydoc and Google now split an examples section the way doctest reads it. Each example holds the text that introduces it as description, and a snippet with the >>> lines, their ... continuations and the expected output, up to a blank line or the next >>> line. Text after the last snippet becomes an example with no snippet.

Examples
--------
To print the numbers:

>>> for i in range(2):
...     print(i)
0
1

Then more text.

Before, Numpydoc gave snippet=">>> for i in range(2):" and put the ... line and the output into the description, together with the text after it. Google kept the whole section as one example with no snippet. Now both styles give two examples:

• description="To print the numbers:", with the snippet holding the for loop, its print(i) continuation and the output 0 and 1
• description="Then more text.", snippet=None

This is breaking for users who read example.description: it used to be the text after a snippet in Numpydoc, and is now the text before it.

Compose writes each example's text, a blank line, then its snippet, so the result reads back the same in both styles. A snippet with no text follows the previous one directly. A Google section with nothing in it still gives one empty example, as before, so auto-detection doesn't change for docstrings whose examples aren't indented under the title. Google compose also stops writing trailing spaces on the blank lines inside a section like Examples.

Parity: 794 of 29,123 docstrings differ from main.

• 254 contain examples: 140 case, 109 generated, 5 stdlib. Two of the generated ones, which mix several styles' syntax, are now auto-detected as Google instead of ReST or Epydoc, because more examples mean more items.
• 540 differ only by trailing spaces in Google compose output: 21 case, 517 generated, 2 stdlib.

145 case files change for these reasons, plus two Numpydoc tests that pinned the old pairing.

Bench on 3.8: parse is 0.99–1.02x of main, compose 0.98–1.02x.