Add an eval-myst directive

[choldgraf]

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
   ```

[tony]

I was able to use {include} ../README.md (docs). What makes this issue's eval-myst different than below?

Since README's are rendered in the more conservative GitHub (vanilla docutil AFAIK) and PyPI (same?), I used pandoc then passed through prettier for styling.

pandoc --from rst --to gfm README.rst --markdown-headings=atx | \
    sed s/"<"/"\("/g | sed s/">"/"\)"/g | \
    sed s/"-   "/"- "/g > tmp; mv tmp README.md

prettier --parser=markdown -w README.md

include root level README.md via docs/index.md:

```{include} ../README.md
-```  < remove the -

versions used:

❯ pandoc --version
pandoc 2.14.0.2
Compiled with pandoc-types 1.22, texmath 0.12.3, skylighting 0.10.5.1,
citeproc 0.4.0.1, ipynb 0.1.0.1
User data directory: /home/t/.local/share/pandoc
Copyright (C) 2006-2021 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

❯ prettier --version
2.3.1

❯ poetry show myst-parser
name         : myst-parser
version      : 0.15.0
description  : An extended commonmark compliant parser, with bridges to docutils & sphinx.

dependencies
 - docutils >=0.15,<0.18
 - jinja2 *
 - markdown-it-py >=1.0.0,<2.0.0
 - mdit-py-plugins >=0.2.8,<0.3.0
 - pyyaml *
 - sphinx >=3,<5

[chrisjsewell]

My, naturally biased, opinion would be; why, what's the point?

Before, Markdown was limited compared to RST, so I could see the use case.
But now, MyST gives you basically all the functionality of RST, so you might as well just use https://github.com/executablebooks/rst-to-myst to convert the "containing" document to MyST then include the README as normal.

Suffice to see, obviously I'm happy for someone else to give it a go, but I doubt I will

I used pandoc then passed through prettier for styling.

@tony as mentioned, rst-to-myst can already do this, no need for pandoc 😉, then also in executablebooks/rst-to-myst#18 I am hopefully making the Markdown output with https://mdformat.readthedocs.io, so no need for prettier 😬

[tucked]

FWIW, I landed here because I need Markdown to handle nesting (e.g. bold links), but RST has rich tables (e.g. bulleted list in a multiline cell). Everything is in Markdown for me already, but I needed an RST table and hit #391 when using eval-rst. So, I switched that doc to .rst and, while I don't currently have use for it, if that doc needed nesting, I would probably reach for eval-myst first.

[tony]

https://github.com/executablebooks/rst-to-myst

rst-to-myst is excellent. Thank you. 90-95% of my RST was ported using it.

I used a mixture of rst-to-myst and pandoc.

I needed to use pandoc and manual editing for corner cases. gave me tables, rst-to-myst would render those in :::{eval-rst}. It'd also render codeblocks in :::{code-block} bash this would do:

```bash

https://mdformat.readthedocs.io

Interesting! Look forward to trying this out. In the meantime I'm using prettier in a Makefile:

format_markdown:
	prettier --parser=markdown -w *.md docs/*.md docs/**/*.md CHANGES

[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 👍

[chrisjsewell]

Note https://rst-to-myst.readthedocs.io/ is now out of alpha, including things like code-block -> code fences, and math -> dollar math

[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