Jupyter Book and Jupytext

[Tom-van-Woudenberg]

Hi @TeachBooks/tu-delft-staff, @TeachBooks/tu-delft-cs-tas , @TeachBooks/escience-center-rses ,

I'm experimenting a bit with Jupyter Book and Jupytext with a few goals:

1. Allow authors to change notebooks in the online text-based editor
2. Create readable diffs
3. Allow readers to download notebooks in a format which they can read.

I managed to get to this book: https://tom-van-woudenberg.github.io/test_jupytext/ with a few conclusions:

• To keep notebook output in the book you cannot circumvent use of ipynb in the git repository so goal 2 of getting readable diffs is not feasible
• With a jupytext.toml file and the command jupytext --sync you can manually sync ipynb and myst:md. It always takes the most up-to-date-version
• With additionally a pre-commit hook in .pre-commit-config.yaml (https://github.com/Tom-van-Woudenberg/test_jupytext/blob/main/.pre-commit-config.yaml) you enforce for every commit a sync. If file needs to be updated these are added before the commit can happen (with the --pre-commit-mode)
• When solving a merge conflict the process is a bit strange as the pre-commit hook also syncs on the changes in the merge commit.
• with pre-commit.ci linked to the repo a similar update is enforced when making changes online. Somehow I get failed pipelines on pre-commit.ci while the updates are still commited to the repo.

I think to make this work properly more work is needed on:

• proporly set up pre-commit.ci so that it doesn't give failed pipelines for unknown reasons
• Looking into how to solve merge conflicts locally properly with the jupytext sync thing happening on the background
• Rethink whether this concept has some value xd

Any comments from the more-experienced-CSy-people here?