Make myst-example directive work with examples with colon fences

[mgielda]

Describe the bug

context I want to use the myst-example directive and put a colon fenced block inside it.

expectation I expected this to work :)

bug But instead I get an error:

myst.md:60: WARNING: 'div': Invalid options format (bad YAML) [myst.directive_parse]

problem This is a problem for people because when showcasing examples, you want all the syntax to work!

Reproduce the bug

The below will fail to parse:

::::{myst-example}
:::{table} Table title! Can even use **markdown**.
:name: this

abc | mnp | xyz
--- | --- | ---
123 | 456 | 789
:::
::::

Looking at the implementation which focuses only on backticks, this is of course to be expected. I did a quick and dirty reimplementation which works for me:

class MystExampleDirective(SphinxDirective):
    """Directive to print an example."""

    has_content = True
    option_spec = {
        "html": directives.flag,
    }

    def run(self):
        """Run the directive."""
        content_str = "\n".join(self.content)
        colons = ":::"
        backticks = "```"
        while colons in content_str:
            colons += ":"
        while backticks in content_str:
            backticks += "`"
        content = f"""
{colons}::{{div}} myst-example

{colons}:{{div}} myst-example-source
{backticks}markdown
{content_str}
{backticks}
{colons}:
{colons}:{{div}} myst-example-render
{content_str}
{colons}:
{colons}::
"""
        node_ = nodes.Element()
        self.state.nested_parse(content.splitlines(), self.content_offset, node_)
        return node_.children

List your environment

Using latest myst-parser from master.

[mgielda]

I know colon-fence is optional syntax, so I didn't want to immediately go and do a pull request - depends on the strategy here. I assume myst-example is a niche use case anyway, so we could just assume if you are trying to import it you have colon fence enabled, but dunno your thoughts here @chrisjsewell.

BTW the directive assumes you have sphinx-panels (for div), which I believe is probably not the best idea. Maybe it makes sense to add the Div directive to the core of MyST if you care about bootstrap? (and if not, just use container?)

But the latter is a smaller problem.

[chrisjsewell]

Hey @mgielda, so... everything in https://github.com/executablebooks/MyST-Parser/blob/master/myst_parser/_docs.py is not public API, hence why it has the prefix _ which is the common practice in sphinx for signalling this.

As the docstring mentions: "Code to use internally, for documentation.", this is purely for containing code to help me build the documentation here.

Of course you are welcome to use it (or just copy and paste in to your own conf.py), but it comes with no guarantee of support 😅

[chrisjsewell]

(all of the code in the module is just very quick and dirty lol, just to implement what I needed)

[chrisjsewell]

If you want to try making a PR for a more "rigorous" directive, then of course I would be interested, but then I expect tests and the like lol

[mgielda]

Ah, OK! I will rename the issue then. I think it makes sense to improve it but it's not extremely critical.