Support for `.md` / `myst-parser`

[tony]

myst-parser (github) supports sphinx roles.

Quick links:

• sphinx.ext.doctest (source: sphinx/ext/doctest.py)
• Related: https://github.com/Erotemic/xdoctest/issues/68
• Also referenced
• as of today at v0.18.0 these are parsed as nodes.literal_block not nodes.doctest_block (message)
• Potentially useful: https://gist.github.com/tonyfast/cfb55f41f5452ef33ec6fbb4e0bda991

Normal directive syntax:

```{doctest}

>>> print(1 + 2)
3
```

eval-rst directive:

```{eval-rst}

.. doctest::

   >>> print(1 + 2)
   3
```

[twmr]

Sounds like a good idea! Thx for the suggestion! I think it makes sense to use the MyST parser for extracting the doctests. Are you familiar with the MyST python api?

[tony]

@thisch Not enough to champion a PR

The reference page should be a good place to start:

• myst_parser.docutils_.Parser (source)
• myst_parser.parsers.sphinx_.MystParser (source)
• myst_parser.parsers.directives.parse_directive_text

[tony]

My ambition would be to use it here: https://libvcs.git-pull.com/parse/git.html (.md, .py)

Right now I have doctest everywhere as its amazingly efficient to have meaningful tests that double as documentation, but I'd like to have tutorials, how to, and explanations where the examples are backed by tests.

Workaround: If using automodule directives, write the doctests at the top of the .py file.