Support myst-parser about sphinx-click HOT 3 OPEN

fwiw, I looked at this today. It seems myst_parser does not seem to be happy with our use of sphinx.utils.nodes.nested_parse_with_titles. That should return a load of docutils nodes but the output is off.

Here's an example using reStructuredText:

and here's the equivalent using Markdown:

You can see that all the directives are outputted in raw form rather than being processed and nested as expected. I'm not sure how you'd go about fixing this, tbh.

from sphinx-click.

If anyone is interested in fixing this, there's a minimal reproducer here.

from sphinx-click.

Yes, and I think that's expected, I've used something similar when messing around with autodoc extensions. For that case, it was fine because the nature of the docstring (rst or md fomat) is known by the user, amd they could fine-tune and select the appropriate parser with eval-rst.

The issue here are:

• the generated doc fragments do not account for which parser it is currently in, e.g.
  

  sphinx-click/sphinx_click/ext.py

  Line 344 in e8cf016

  yield '.. program:: {}'.format(ctx.command_path)

  
  This could have an if statement to generate either format. It should be within an with to appropriately start-end the blocks
• the api is monolithic, but something along the lines of sphinx autodoc would probably be more manageable

I think the only relevant references here is sphinx-autodoc2, e.g. see their approach here (navigate to the concrete implementations for myst and rst)

from sphinx-click.