Can we have subsections in Examples?

[ev-br]

For a docstrings with several examples, it would be nice to be able to clearly separate them:

Examples
-------------

Here we show two examples of our awesome function.

First example
~~~~~~~~~~

foo

Second example
~~~~~~~~~~~~~

bar

Just tried it and it seems to break the doc build:

/home/br/repos/scipy/scipy/doc/source/reference/generated/scipy.interpolate.RegularGridInterpolator.rst:33: CRITICAL: Unexpected section title.

Interpolation and extrapolation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [  2%] reference/generated/scipy.interpolate.Akima1DInterpolator.__calwriting output... [  3%] 

<snip>

dumping object inventory... done
build finished with problems, 1 warning.
make: *** [Makefile:118: html-scipyorg] Error 1

To illustrate the origin: note the As a second example, we... transition in
http://scipy.github.io/devdocs/reference/generated/scipy.interpolate.RegularGridInterpolator.html#scipy.interpolate.RegularGridInterpolator

Not sure if it's even that good of an idea, or how difficult it is to implement.

[larsoner]

FYI one workaround is to bold a single line, like:

**First example**

...

**Second example**

...

It doesn't create anchors which is unfortunate, but it at least makes things that look a bit like headings, e.g.:

https://mne.tools/stable/generated/mne.decimate_surface.html