Transition docs to use MyST?

[consideRatio]

The JupyterHub org has been using Sphinx systematically, and this project does it as well. In the past using rST was the only option, but since MyST has come - we can now use Markdown based formatting together with Sphinx.

The reason classical markdown wouldn't work, is that classical markdown couldn't feed into the Sphinx system that is meant to handle documentation with multiple files etc that builds up to a full website.

We have adopted MyST in the jupyterhub/jupyterhub project, jupyterhub/zero-to-jupyterhub-k8s, and perhaps a few more. So far, the experience has been positive in this projects, but it is a bit of chore make the transition.

I'd be very happy to make such chore work as I just love to work with MyST compared to rST that I never have become fluent with, so I feel happy about putting in the effort.

My key motivation for a switch from rST to MyST

1. I believe Markdown makes it easier for anyone to contribute, as people, myself included, is more familiar with markdown than rST.
2. I've seen the prettier autoformatter be able to autoformat black and yaml within code examples part of the MyST markdown files, and that in turn has catched a few invalid examples and such which have made me happy!
3. I've also seen prettier autoformat some frustrating Markdown tables so that one doesn't need to do that manually.
4. MyST is supported by a living open source ecosystem of tools that also have projects integrating with the Jupyter ecosystem in general, for example the jupyter book project to convert MyST Markdown + Jupyter notebooks into a nice website. To use it typically means to help it develop.

Related

• Background to the creation of MyST
• About the rst2myst project
• Markdown+MyST, and, or, rST? team-compass#350 - discussion about adopting MyST in JupyterHub org repos
• switching to myst markdown in docs zero-to-jupyterhub-k8s#1628 - the first transition to MyST in a JupyterHub org project
• docs: 100% MyST Markdown zero-to-jupyterhub-k8s#1974 - the first final migration, converting all rST documents to MyST markdown documents.

[lambdaTotoro]

I had a few hiccups with RST as well. I also had a look at MyST and it seems to offer a great many features and level of control. Far beyond what's necessary for us, but that shan't stop us. I'd be glad not to stumble over RST anymore, and I think markdownisher syntax might be helpful not just for us but for many potential future contributors.

If you're willing to do the transition, I think I'd be happy to switch.