Proposal: Replacing Notebooks with MyST Markdown

[HaoZeke]

Notebooks require commits every time they change (are executed) since they are essentially large blobs of json. MyST Notebooks allow for plain markdown files to be processed as notebooks using jupytext.

For a before and after example (check the raw rendering):

• A Notebook
• Corresponding MyST markdown

If there is of interest I can try to make time over the weekend to open some concrete PRs.

[liamhuber]

If there is of interest I can try to make time over the weekend to open some concrete PRs.

Hi @HaoZeke! If you can make time to do this, that would be lovely. There are special tools for diffing whole notebooks, etc, but I have never been the biggest fan of NBs to begin with -- IMO, writing the content as plain-(and meaningful-)text to begin with is far preferable to coming up with workarounds after you already have the json mess!

I took only a quick peek, but I see that jupytext is already available on conda-forge, so at the moment I don't foresee any fundamental obstacle to switching over to MyST 😄

[jan-janssen]

Hi @HaoZeke and thanks for the suggestion, I briefly looked at MyST and I wonder if it also contains the output of the notebook. Having the resulting plots already included in the example makes it easier for the users to follow, so I would be interested to understand how the output can be stored in an MyST notebook: https://pyiron.readthedocs.io/en/latest/source/notebooks/first_steps.html#Analyze-the-calculation

[HaoZeke]

Hi @jan-janssen, it is definitely supported; along with the more interactive widgets, but I'll get back to you on the specifics of where and how it gets inserted; my guess is it gets written out to a file during the Sphinx build.

Thanks for seconding the plan @liamhuber! I'll have a PR this weekend then for further comments.