Add support for custom directives in examples sections

[akaszynski]

tl;dr
Implement this: https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.oaconvolve.html#scipy.signal.oaconvolve

Feature Request: Allow Hooks to add directives to examples sections

matplotlib has out of the box support for automatically generating images from example documentation via the .. plot:: directive in:
https://matplotlib.org/2.0.2/devel/documenting_mpl.html

When combined with numpydoc's numpydoc_use_plots according to numpydoc configuration, matplotlib figures are automatically generated for any examples containing import matplotlib. It's amazing and let's add plots to any example. See scipy.signal.oaconvolve for an example.

We're implementing a monkey patch for this in pyvista/pyvista#1457 and our docs now look really cool:

Implementation details:
https://github.com/pyvista/pyvista/blob/0b2a8cf0664ac0f89f621d4da42bc71593cda00b/doc/conf.py#L154-L187

Possible Approach

We'd like to see this implemented out of the box. One way to implement this would be to add special configuration parameters for pyvista or matplotlib, but that's not "future-proof" and will require a variable for each rubric you'd like to support. Instead, you could add a config that allows a tuple of (import_statement, directive_to_add) that checks for any imports and then adds the directive and indents to section of the example.

Thanks

Sphinx is amazing and we really appreciate all your work supporting this project.