Compatibility with RST Glossaries

[rowanc1]

trafficstars

We should add compatibility with Sphinx/RST glossaries (which are based around indentation). At the very least the compatibility warning should be improved with a link to how to do this in Sphinx.

See https://github.com/executablebooks/MyST-NB/issues/544#issuecomment-1734574664

[agoose77]

I suspect there will be more than one instance of places that we want to break Sphinx compatibility for strictness. I wonder whether we should introduce compatibility, but hide it behind a feature flag. The idea would be that jupyter-book could enable this flag, but MyST-md would have no need of it.

Then again, jupyter-book would probably just define a custom high-priority transform that normalises the glossary.

Which of the two do you prefer?

[rowanc1]

Yes, I like doing this via a flag, and having pre-defined configs for different compatibility stories (e.g. sphinx, quarto, etc.).

The was I had played out the development of this is to look at the parsed body content in the directive, if it has definition lists, then it is the new format, if not, parsing that based on the body's raw text in the directive, and calling the parse function after splitting on new lines. The outcome of this directives run function would then always be a defList.

[agoose77]

The was I had played out the development of this is to look at the parsed body content in the directive,

I had the same thought! I like the idea of gating that behind a feature flag so that we can have a "strict" parser for core MyST, but more liberal for JB.