A proposal for this repository

[choldgraf]

Now that we have a myst (or "imd" or whatever we wanna call it) prototype, we could use this repository for just the docutils bridge part of the prototype. What if we:

• Split out the extra docutils class that @chrisjsewell has created from his mistletoe fork, put it in here. (make it clear that this repository depends on Chris' fork of mistletoe...or we could also move that fork into the EBP as well)
• Put the Sphinx parsers in here as well
• Use the docs/ folder of this repository as the growing documentation for the Myst parser

I think this could make it easier to start iterating and documenting, and would also make it clear what changes to Mistletoe we should upstream, vs. what we can keep as our own docutils-specific extension.

[choldgraf]

Update: we have docs!

https://markup-test-cases.readthedocs.io/en/latest/examples.html

That examples page is built from this file:

https://github.com/ExecutableBookProject/markup_test_cases/blob/master/doc/examples.md

[chrisjsewell]

or we could also move that fork into the EBP as well

I think that might be easier, because the good thing now is that I can have all of the commonmark/mistletoe integration testing running in one place, and checking that none of the syntax extensions are conflicting with the standard Markdown syntax.

For testing, you should also consider adding test cases to https://github.com/chrisjsewell/mistletoe/blob/myst/test/test_sphinx/test_sphinx_builds.py, where we can have tests for multiple, smaller sphinx project builds, focussing on particular aspects of the syntax.

Can you make me a team member of ExecutableBookProject, so that I can create a fork here?

[chrisjsewell]

and would also make it clear what changes to Mistletoe we should upstream, vs. what we can keep as our own docutils-specific extension.

At the moment, it is simply everything in https://github.com/chrisjsewell/mistletoe/blob/myst/mistletoe/docutils_renderer.py is myst specific, and everything in https://github.com/chrisjsewell/mistletoe/blob/myst/mistletoe/block_token.py is upstream-able.

This is going to get a bit more tricky though when I start to implement block level extensions, like field lists and comment blocks. Because then you have to subclass/rewrite a number of the standard block tokens to handle 'state transitions' to the new tokens. For example, here in Paragraph you have to check if you are entering a comment/field list block.

[jstac]

@chrisjsewell , I've made you a co-owner of ExecutableBookProject --- or at least I've sent you an invite. Let me know if you don't get it.

[chrisjsewell]

Yeh cheers. In the first instance I look at moving my fork of mistletoe over to here then.