Sharing assets between `myst-parser` and `markdown-it-myst`

[choldgraf]

If we have a core spec that we want both the Python and JS implementations to support, we could also consider sharing some assets between them. For example:

• Testing assets / fixtures
• Regexes
• Definitions of standard HTML outputs for certain tokens
• Anything else?

These could help us reduce maintenance burden in myst-parser and markdwon-it-myst, and could also help us ensure that they produce identical outputs for certain myst syntax.

[rowanc1]

I have been developing some of the fixtures here: https://github.com/executablebooks/markdown-it-myst/tree/master/fixtures

These were loosely based on: https://github.com/executablebooks/MyST-Parser/tree/master/tests/test_renderers/fixtures

With the idea of sharing. 👍

If we get to some standard/tested html outputs on myst --> html (without sphinx) then we can also start sharing the styles for the components. I will think a bit more about how to do that from an infrastructure standpoint as we are doing that internally in the next month as well.

[chrisjsewell]

Yeh exactly, and all of the fixtures in markdown-it-py are similarly language independent; just text files defining the input markdown and expected HTML output

[chrisjsewell]

They all have the same format

Test title
.
Input text 
.
Expected HTML
.

Next title
...

[rowanc1]

Are you doing something on the test runner side to fill in the </end> tags? Or am I looking to the wrong place and this is internal sphinx maybe?

For example:

--------------------------------
Admonition with title:
.
::: {admonition,other} A **title**
*hallo*
:::
.
<document source="notset">
    <admonition classes="other">
        <title>
             A 
            <strong>
                title
        <paragraph>
            <emphasis>
                hallo
.

[chrisjsewell]

Ah no these are comparing to "pseudo" XML of the sphinx syntax tree, rather than the final HTML. There are some that compare to the HTML, but obviously in the sphinx context, these are easier to debug

[mmcky]

I had a conversation with @rowanc1 and @AakashGfude this morning and we were thinking it might be a good time to start working on a central set of multi-target test cases which could help with coordinating between sphinx, and javascript implementations; in addition to coordinating (or documenting behaviour) for outputs such as html, tex; and help in producing a myst specification.

@chrisjsewell what do you think about a modified test fixture structure to support tests at different pipeline levels with tags such as:

Test title
.
Input text 
.sphinx
<Expected Sphinx AST XML>
.html
<Expected HTML>
.tex
<Expected LaTeX>

---

Next fixture
...

I guess this breaks the simplicity of parsing them with three break points and adds a layer of interpretation on the tag based on test context. So would be interested in your thoughts.

The thinking is that we can then setup a central repo to house a central store of test fixtures that the other repos can use as a test case in their own test suites as a standard source of tests.

[mmcky]

@chrisjsewell would you have any time to comment on this issue. We are thinking it might be nice to have a centralised test suite that documents the various stages of the pipelines and/or outputs that can be used to test against for various development work (primarily thinking through javascript vs. python implementations). The suggestion above was the "easiest" way to extend the current framework but you may have better ideas on a good data format / layout.

[choldgraf]

After a conversation with @rowanc1 and @damianavila we decided to open up a separate repository to track to-do items and discussion points around implementation-agnostic information about the MyST specification (such as those discussed here). I believe @rowanc1 is planning to work a bit on the JavaScript parser for MyST, and this may also be an opportunity to understand where shared infrastructure can help: https://github.com/executablebooks/myst-standard

(note, there's no infrastructure or tooling in that repo currently, it is just a place to track action items and coordination, but perhaps one day it might also be the home of shared test infrastructure, schemas, etc)

[rowanc1]

Thanks @choldgraf - been looking into this a bit today and at the existing patterns in the MyST-Parser repo, there are some existing ways we are pulling in the test cases for common mark (e.g. spec.sh here) that could become common across the stack. I will continue to duplicate the fixtures from the python repo and extend them into .html as per @mmcky's comment and then start some discussion over there soon!

[chrisjsewell]

Well you won't actually find the (initial) commonality in myst-parser, you will find it in markdown-it-py and mist-py-plugins. Everything in JavaScript (well actually I hope you are using typescript 😉) should flow through there, as in you should first be parsing everything to markdown-it tokens

[chrisjsewell]

But yeh let me know if you need any help

[rowanc1]

Ok - had not found these: https://github.com/executablebooks/mdit-py-plugins/tree/master/tests That helps a lot with my testing! And yes - all in .ts 💥

[chrisjsewell]

Yep the first thing is that we have parity between the markdown-it extensions we use in python and typescript 👍

[chrisjsewell]

This will also make it easier 😉: https://github.com/executablebooks/markdown-it-myst/pull/31