Create myst-example directive and change documentation to use it

[jbms]

I think the myst-example directive is more of a long-term and worthwhile goal. The solution [in #247] is only meant to satisfy #162 per user's request/feedback.

Originally posted by @2bndy5 in #247 (comment)

[2bndy5]

I took a swing at this and it was really easy to re-use the same directive class from our rst-example directive for a myst-example directive. So, that is a first step. There are some MyST examples that can't be used with this though (eg. section headings and markup representing <hr> elements).

My original vision was to feed a single directive multiple code-blocks with the language set, then render them in a set of tabs whose labels correspond to the code-block's language. I was imagining something like

.. doc-example::

    .. code-block:: rst

        Some ``syntax``.

    .. code-block:: md

        Some `syntax`.

Alternatively, it would be more ideal to have rST content converted to MyST syntax and render both syntaxes as a set of tabs (whose labels correspond to the syntax name "rST" and "MyST") sharing a single rendered result. I think this would be better as a derivative of the rst-example directive. I'm not sure if it should be done the other way around though (take MyST content and convert it to rST).

This will take me some time as the parser used by the state machine seems to be automatically determined based on the source file's suffix.

[2bndy5]

Damn. It looks like the rst2myst tool (still in beta) doesn't support the latest docutils.

I'll just submit a patch for what I have and put my original vision (a bit zealous even for me) on the back burner (again) till we have a feasible tool/lib to convert rST to MyST.