DOCS: Add example directive

[choldgraf]

This is a lightweight directive that lets you write some source markdown, and displays the "raw" and "rendered" version of the text so that others can learn from it. It is meant to make it easier to quickly write demonstration content without needing a ton of duplicates in your code.

I started it off in this repository so that we can use it in Jupyter Book, but if others find it useful we could port it into a standalone extension.

[chrisjsewell]

Hmm, it's up to you, but I don't really think here is the right place for this. Also to note, I've done something similar in https://sphinx-design.readthedocs.io/en/latest/tabs.html#tabbed-code-examples

[choldgraf]

this one is purely for convenience sake - I agree it's better someplace else in general, but the code is quite simple so I just wanted something quick for now that I could use as part of the sphinx-design refactor.

Maybe instead of having it in the book theme I can just hard-code something in the docs of jupyter-book to re-use, so that it's clearer this isn't meant for a long-term home. I just don't have time to create a new sphinx extension from scratch right now.

Longer term, maybe we create a sphinx-demo extension or something? I like the tabbed example as well - though would prefer something that shows both the source and the result without requiring user to click between them

[choldgraf]

Random idea - what about putting this in sphinx-design? I'd be fine bringing this functionality as an "extra" in sphinx-design - so long as we can have examples that show both the source and the result at the same time, without being hidden behind tabs or dropdowns.

I actually think the implementation could be a bit nicer if we used the SD {grid} directive anyway. That said, I don't have many cycles to work on this and don't want it to block the sphinx-design update in jupyter book, so may just do a hacky thing now

[choldgraf]

I thought about @chrisjsewell's suggestion and decided to turn this into a lightweight python package that could be re-used and developed on its own. That now lives at the address below:

https://github.com/executablebooks/sphinx-examples

This PR is now re-worked to re-use that package in our documentation. It currently loads sphinx-examples from the GitHub repo ZIP file just to preview and iterate on it, but we can make a release and use the version on pypi before merging here.