Add an `eval-myst` directive

maintainer note: you can use https://rst-to-myst.readthedocs.io/ to convert one or more files from RST files -> MyST

---

I was just looking through the Sphinx issues, and saw that one of the top-rated issues included asking how to include a markdown file in an rST file.

In the myst-parser, to accomplish the opposite, we suggest users use eval-rst to include rST files in their markdown files (https://myst-parser.readthedocs.io/en/latest/using/howto.html#include-rst-files-into-a-markdown-file).

So they can do:

# My title

```{eval-rst}
.. include:: myfile.rst
```

So perhaps it would also be useful if MyST Parser defined an eval-myst directive that could be used within rST documents, and could do things like:

My title
========

.. eval-myst::

   ```{include} myfile.md
   ```

[chrisjsewell]

With docutils>=0.17 you can now do:

.. include::
   :parser: myst_parser.docutils_

.. include::
   :parser: myst_parser.sphinx_

Although, I want to stress I don’t consider this “officially” supported in myst-parser, since it is not an intended use case and completely untested. So I won’t be accepting any bug reports regarding it failing for any reason

[chrisjsewell]

but I needed an RST table and hit #391 when using eval-rst

Obviously here I would rather spend the time to fix the issue, than introduce an eval-myst

rst-to-myst is excellent.

Good to hear 😄 I was just trying to “finalise” it, then promote it more in the docs here

gave me tables, rst-to-myst would render those in :::{eval-rst}

This should only be the case for RST tables that are not “compliant” with Markdown tables, e.g. ones with cells spanning multiple columns/rows, otherwise they are converted. If you could provide an example of a table that you think should have been converted but was not, that would be helpful thanks.

It’d also render codeblocks in :::{code-block} bash … as ```bash

yep that makes sense and can be added 👍