Create `myst-example` directive and change documentation to use it about sphinx-immaterial HOT 2 CLOSED

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.

from sphinx-immaterial.

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.

from sphinx-immaterial.