Support myst-parser

[LecrisUT]

Currently the generated code is specific for rst documents such that the following does not work:

```{click} module:parser
:prog: hello-world
```

There is a workaround using:

```{eval-rst}
.. click:: [scikit_build_core.cli.main:skbuild](module:parser)
   :prog: hello-world
```

However it would be good to have built-in to use the appropriate parser (i.e. rst) for the generated code.

[stephenfin]

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.

[stephenfin]

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

[LecrisUT]

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)

[kdeldycke]

For the record, I just added support of MyST syntax for the click:example and click:run Sphinx directives.

It will be available in the upcoming Click Extra 5.1.0 (which is pending Click 8.2.2 release).