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

[Günter M. <mi...@us...>]

Since [r8916], "myst" is a parser alias that points to the module
`myst_parser.docutils_`. You can use, e.g., 
`docutils-cli.py --parser=myst` to parse MyST Markdown input.

Docutils' config documentation links from the section
https://docutils.sourceforge.io/docs/user/config.html#myst-parser
to the upstream documentation.

I am not in favour of removing "recommonmark" support as long as
"recommonmark" is widely available (e.g. as Debian package).

We may consider changing the "commonmark" and "markdown" parser aliases to
a wrapper module that selects whichever of "myst" or "recommonmark" is
installed at the user's system.

Is there anything else that would be better done on the Docutils side?



---

** [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.