Investigate using Myst for documentation

[patrick91]

Myst seems quite interesting, it does support some stuff we have already built: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html

Maybe we can start using it and update the website to use a parser for myst :)

also supports autodoc via sphinx, which could be nice to have https://myst-parser.readthedocs.io/en/latest/sphinx/use.html#use-sphinx-ext-autodoc-in-markdown-files

[patrick91]

worth investigating this too by Stripe: https://markdoc.io/

[estyxx]

So I start looking at this to generate documentation and I had a try setup an initial sphinx configuration with myst_parser. It works well but the problem is that we want Markdown as the output of the sphinx-build and by default Sphinx doesn’t have it in [his list of builders](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) so the only thing that I found to build markdown is this package https://github.com/clayrisser/sphinx-markdown-builder but it’s not maintained anymore and has some bugs…

So I forked and tried to fix it in order to generate some valid Markdown atm...

But I want to check also if this is the right path, or if you have other ideas/tools in mind @patrick91 ?

[patrick91]

for the website I think we should keep as much as we can in JS/TS, I've seen this https://github.com/executablebooks/mystjs but not 100% sure it is worth putting effort into this just yet, I think we'll have a new design for the website at some point in the next few months. I think we can decide then what we want to do :)

[patrick91]

Going to close this, I'll do some work on the website around december and hopefully I'll get around some of these things 😊