Great summary. Chiming in wrt my workflow (hundreds of notebooks used for research, collaborative development of university courses, graduate student projects etc.) I’ve found jupytext to be transformative. A couple of comments from my own experience:
- I keep the python version and the json version in different folders. This makes diffing, grepping, adding files to the git index etc. easier. The ipynb files reside one level up, but aren’t committed to my git repo. My global jupyter_notebook_config.py looks like this:
c.NotebookApp.contents_manager_class = "jupytext.TextFileContentsManager" # noqa
c.ContentsManager.preferred_jupytext_formats_save = "py:percent" # noqa
c.ContentsManager.default_jupytext_formats = "ipynb,python//py" # noqa
c.ContentsManager.default_notebook_metadata_filter = "all,-language_info"
c.ContentsManager.default_cell_metadata_filter = "all"
This passes almost all metadata and pairs mynotes.ipynb with python/mynotes.py, creating the python folder if it doesn’t exist.
I use the pre-commit package to run black, reorder-python-imports and flake8 on every python file, which is obviously a major improvement for informative diffs.
For those of you using nbgrader-- you’ll need to disable jupytext when you convert source notebooks to student released versions. You can do that by editing the formats metadata string for that notebook to “ipynb” only.
Here’s an example of a set of teaching notebooks with their py:percent counterparts: EOSC 213
Bottom line – jupytext is the missing piece I’ve been looking for since I started working with IPython notebooks