Description
My request is actually the reverse of #639
The conclusion of #639 was "come as you are". I was liking it at the time but I'm not liking it anymore.
My rational is that we are a Sphinx based theme, our goal is to extend as much as we can what Sphinx does and make it better, not promoting new tool (even when they are great as Jupyterbooks or myst).
Why ? because then not only we are making ourselves bound to their releases processes but more importantly we are forcing users to not only learn sphinx and rst but also learn all this extra-lib that they may not know/need.
myst in itself is parsing .md files to .rst before sending them to the Sphinx builder. It's great and it will work without any changes from our side so why not stick to the .rst way ?
I know that many of you are big users of jupyterBooks so you are more used to myst than I am and you feel it's easier.
I still think that there are more people like me than like you as this theme can be used for things that are 100% unrelated to Jupyter. Even though I understand that for simple text documentation it's just fine and I agree that .rst can be a bit convoluted sometimes but whenever you try to do more complicated things it becomes:
- messy: How can one consider these tabs in .md easier to read than an indented .rst directive https://github.com/pydata/pydata-sphinx-theme/blob/main/docs/user_guide/theme-elements.md ?
- difficult: it's forcing people to understand .rst (where the directives are actually documented) and the .rst parsing performed by myst as myst didn't redocumented docutils entirely as this one: https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table
- non reusable: This custom directive can only be used in a .md file and not in a pure sphinx based one: https://github.com/pydata/pydata-sphinx-theme/blob/main/docs/_extension/gallery_directive.py, I think it's a mistake.
Note that I would happily do as in sphinx-design where they decided to promote myst by showing for every commands the 2 writting options: https://sphinx-design.readthedocs.io/en/latest/grids.html but my suggestion here is to harmonize the writting of our docs to allow new users to participate without enforcing a new markup language.