Jupyter and GitHub - alternative file format

The notion of different formats for different reasons is a powerful one I think:

If you “restart kernel run all / export as ipynb” the document is a complete record of code + outputs; it doesn’t mean you can replicate the run (you’d need a definition of the computational environment for that, which is the subject of other discussions (eg guix)) but is does mean you have something that is shareable and works as a discussion object.

One workflow I’ve found useful is jupytext pairing either markdown or python files with an ipynb doc in a hidden directory; this gives me a simple diff-able text file, with a complete view (text + code + outputs) when I open the doc in a notebook UI. So here I am using the md/py file for the text-code and then a separate file to give me a view of the outputs.

It’s also worth noting that my view of the notebook may differ in semantics from the content of the code in the text file, and the visual appearance may differ too. For example:

  • I use the active-ipynb tag a lot on code cells that lets me see and run the code cell normally in the notebook view, but comments it out in the py/md text files.
  • I use extensions to dynamically style the view I have of a notebook; this might include collapsed sections, dynamic application of style based on tag values etc.

To render the “styled” view of the notebook would require either the previewer to run the same presentation extensions I run over the view, or me to render the document as eg html via a custom export template and share that.

I think this is a really powerful idea (cf. nbexplode, sqlitebiter etc.).

Pondering differently granular table definitions that could support such a backend (where documents are essentially just views over the database) and comparing them to structural elements in a text representation could be interesting…

2 Likes