Setup sphinxcontrib-myst extension for quickly generating myst documents from RST

[mmcky]

hey @chrisjsewell we are thinking about translating a bunch of RST into myst syntax (for testing purposes). I proposed that we throw together a simple sphinx extension and write a myst translator from the sphinx AST. I don't think it would take too much work.

Can anyone think of a better way for auto generating the myst docs from rST (i.e. custom script using known rST regex)?

[chrisjsewell]

(Copies from Zulip)

It makes sense to do the conversion using an AST-to-AST approach. However, the complication I foresee is that (a) roles/directives are run during the initial docutils parse, meaning it would be hard to work out what these were originally, and (b) you would be getting the AST after it has passed through a bunch of transforms, making it even more difficult to determine the original document structure.

[chrisjsewell]

Ideally you would patch the docutils parser to just store the raw contents of a role/directive in some node type, without actually running them.

[mmcky]

Thanks @chrisjsewell perhaps something more like https://github.com/h-ohsaki/rstparse would be a better approach without transiting the docutils ast

[mmcky]

@chrisjsewell do you think we could just use a set of pandoc filters to handle the roles and directives?

[mmcky]

Alternatively I think the best way to go might be to:

1. write a simple parser looking for roles and directives
2. split the document up into the components {[rst,role,rst,directive,rst,....]}
3. give simple rst to pandoc for conversion and parse role and directive directly

[chrisjsewell]

@chrisjsewell do you think we could just use a set of pandoc filters to handle the roles and directives?

Yeh that could well be possible. I would suggest trying out panflute