Move document format slowly to markdown?

[zklaus]

Many people (for example me) struggle with writing documentation in restructured text. Some of the criticism can be read in this blog post.

I think we can see in our own documentation that particularly when many people contribute to a document over a long period of time, the unclear conventions around headers and other difficulties make it sometimes hard to improve the documentation.

Markdown has established itself as a cleaner alternative, and with MyST there is now a credible way to employ it with Sphinx.

If we decided to move the documentation to markdown, we could do so gradually, first adding the MyST parser and allowing the addition of .md files alongside the current .rst, then slowly migrating the existing docs over. Or we could try to do one big migration using rst-to-myst, possibly keeping around a few rst files that trouble us.

What do you think?