[Docutils-develop] [docutils:feature-requests] #86 Replace recommonmark with myst-docutils

[Chris S. <chr...@us...>]

That great cheers, indeed the aliases are the main thing here:
I would prefer docutils itself did not override the `myst_parser.docutils_.Parser` (as it does for the recommonmark parser)  and instead any required changes/improvements were implemented directly in myst-parser.

Obviously, I will leave it up to you guys, as to any testing you want to include directly in docutils.

For the "markdown"/"commonmark" alias, I would certainly be for it using myst-parser, but note that this would currently be equivalent to: `docutils-cli.py --parser=myst --myst-commonmark-only=yes`.
This "turns off" any syntax that is not strictly part of https://spec.commonmark.org/0.30/, such as tables and footnotes.
(you can see the implementation logic at: https://github.com/executablebooks/MyST-Parser/blob/0f2902ab5eb6236805ed24dc387b34c00fe41744/myst_parser/main.py#L226)
There could perhaps be a slight override for this.

Similarly, it might be interesting to note that the Github Flavoured Markdown spec: https://github.github.com/gfm/, is roughly equivalent to: `docutils-cli.py --parse=myst --myst-enable-extensions=linkify,tasklist --myst-disable_syntax=footnote_ref,footnote_def`.
The only thing that cannot be replicated from that spec currently is strikethrough: it is available in the markdown-it parser, but docutils does not have any native node class to support it :(



---

** [feature-requests:#86] Replace recommonmark with myst-docutils**

**Status:** open
**Group:** Default
**Created:** Sun Jan 02, 2022 01:26 PM UTC by Chris Sewell
**Last Updated:** Sun Jan 02, 2022 01:29 PM UTC
**Owner:** nobody


Hey guys,

As discussed in https://github.com/readthedocs/recommonmark/issues/221, recommonmark has been officially deprecated in favour of https://github.com/executablebooks/MyST-Parser/.

In myst-parser v0.16, I added first-class support for direct docutils use (as opposed to via sphinx) and introduced the parallel https://pypi.org/project/myst-docutils/ distribution, which is myst-parser but without explicit install requirements on docutils or sphinx, i.e. you can install myst-docutils with any version of docutils and it will work without sphinx installed.

receive(see https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md#0160---2021-12-06, https://github.com/executablebooks/MyST-Parser/issues/347, and https://myst-parser.readthedocs.io/en/latest/docutils.html) 
receive
receiveIn the master branch (and soon to be myst-docutils v0.17) I have also been working to improve the rigour of the behaviour/testing against this parser.
(as an example, I believe your current recommonmark solution does not actually work properly with code fences, because it does not syntax highlight the code, see: https://github.com/executablebooks/MyST-Parser/pull/478)

The fixture test sets, essentially provide a full specification of the Markdown -> docutils AST conversion (pre-docutils-transforms):

- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_syntax_elements.md
- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_roles.md
-  https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_directives.md

and are currently tested in the CI for myst-docutils against docutils v0.16, v0.17 and v0.18: https://github.com/executablebooks/MyST-Parser/runs/4670995311?check_suite_focus=true

I'm also happy to recieve any feedback /  improvement suggestions to facilitate this, and have opened a parallel discussion topic here: https://github.com/executablebooks/MyST-Parser/discussions/487

Cheer,
Chris



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.