docs(agama): write pygment lexer or highlight.js grammar

[jgomer2001]

I'd like github website to do syntax highlighting of flows written in agama DSL, however this is only available to languages that have important verifiable adoption:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#syntax-highlighting https://github.com/github/linguist/blob/master/CONTRIBUTING.md#adding-an-extension-to-a-language

Instead, I think we can at least make Python-Markdown (used to render Jans docs) understand agama snippets. To my understanding we need to contribute with a pygment lexer for this purpose:

https://python-markdown.github.io/extensions/code_hilite/ https://pygments.org https://pygments.org/docs/lexerdevelopment/

It may take a lot of time to get it merged. A shortcut can be trying highlight.js. If we can prove that highlight works in our generated docs site, then we can create a 3rd party grammar:

https://highlightjs.org https://highlightjs.readthedocs.io/en/latest/language-contribution.html https://github.com/highlightjs/highlight.js/blob/main/extra/3RD_PARTY_QUICK_START.md

This sounds the more convenient path.

[iromli]

@jgomer2001 as for as i know, creating custom lexer can be done as 3rd-party package that doesn't need to be merged into upstream pygments project.

Ref:

1. https://pygments.org/docs/plugins/#defining-plugins-through-entrypoints
2. https://www.iamjonas.me/2013/03/custom-syntax-in-pygments.html old article but works!

[ossdhaval]

@moabu Can you please assign this feature request to the appropriate person if we are planning to undertake this.