MyST-Parser VS sphinxcontrib-mermaid

Sphinx along with MyST-parser to write documentation in markdown. I recently discovered portray which seems like a nice alternative as it supports markdown by default for both generic documentation and docstring in modules, class, methods and functions.

https://github.com/executablebooks/myst-parser :

> MyST is a rich and extensible flavor of Markdown meant for technical documentation and publishing.

> MyST is a flavor of markdown that is designed for simplicity, flexibility, and extensibility. This repository serves as the reference implementation of MyST Markdown, as well as a collection of tools to support working with MyST in Python and Sphinx. It contains an extended CommonMark-compliant parser using markdown-it-py, as well as a Sphinx extension that allows you to write MyST Markdown in Sphinx.

https://markdown-it-py.readthedocs.io/en/latest/ :

> *Follows the CommonMark spec for baseline parsing;

This project is just the first step towards making Spyder an educational tool. In the future, we hope that we can develop the infrastructure necessary to support in-IDE tutorials, by improving the tools like Jupyter Book, sphinx-thebe, MyST-Parser which will provide better integration to write educational tutorials.

And if you're using Sphinx to document, you can also just inline the diagrams in your .rst docs: https://github.com/mgaitan/sphinxcontrib-mermaid