Comment by jpfr | Hacker News Reader

Comment by jpfr | Hacker News Reader

Parent Full thread

Jupyter notebooks seem to be the modern form for literate programming.

People are writing entire books in the literate style:

http://nbviewer.jupyter.org/github/rlabbe/Kalman-and-Bayesia...

The style is similar to literate classics like "Structure and Interpretation of Computer Programs" and "Structure and Interpretation of Classical Mechanics".

The only downside is version control. Jupyter uses a custom file format. It is difficult to work with colleagues on the same notebook, since we cannot use the usual code-versioning tools (git/diff/etc.) to manually merge together concurrent changes.

Anybody knows a good solution for this?

You can use a filter in your gitconfig to strip away the outputs, and thus make it play nicer with git [0].

gitconfig:

  [filter "nbstrip_full"]
      clean = "jq --indent 1 \
              '(.cells[] | select(has(\"outputs\")) | .outputs) = []  \
              | (.cells[] | select(has(\"execution_count\")) | .execution_count) = null  \
              | .metadata = {\"language_info\": {\"name\": \"python\", \"pygments_lexer\": \"ipython3\"}} \
              | .cells[].metadata = {} \
              '"
      smudge = cat
      required = true

gitattributes:

  *.ipynb filter=nbstrip_full

[0] http://timstaley.co.uk/posts/making-git-and-jupyter-notebook...

> Jupyter uses a custom file format

For those curious, the ipynb files are json files, and the code is stored in an array of cells, as string entries

README files on higher level (modules, subsystems), comments on the level of individual files.

org-babel:

https://orgmode.org/worg/org-contrib/babel/

> Anybody knows a good solution for this?

It's right here where you're commenting: org-mode.

Reply on news.ycombinator.com