Writing and Reviewing Jupyter Notebooks

2023-05-18T00:00:00+00:00

A recent project involves delivering a finished product as a collection of Jupyter Notebooks. This process involves using Emacs for writing, Git for version control, and a slightly tricky process for enabling non-Jupyter, non-Emacs users to perform document review.

Writing—just like programming—ideally includes a review process before anything is delivered to the client. Even first drafts need at least two readers before delivery. I’ve previously discussed how I use Org Mode and Pandoc to deliver DOCX files, and DOCX or ODF files unfortunately remain the easiest way to track changes and edits among word processor users.

Since Jupyter Notebooks are basically JSON documents, the best way to keep track of changes and revisions is using some kind of version control. Here is one process using Git and GitHub.

When my notebook files are ready for review, converting them to DOCX files is pretty straightforward.

First, I use the jupyter command line tool to convert to Markdown, like this:
```
jupyter nbconvert --to markdown *.ipynb
```

Next, I use Pandoc to convert to DOCX using a reference link.

for file in *.md
    pandoc --reference-doc $path_to_refdoc -o $file.docx $file
end

Renaming files with Dired

At this point, I needed to rename all of the DOCX files and move them to the proper shared folder, so my reviewer could get to them and know what’s going on. We have a naming format for filenames that helps us track project and versions, so all of the files needed to have at least a v1 in them.

Emacs has a file manager called Dired, which contains powerful features that allow you to modify directory contents just like any other buffer. I now had a bunch of files that ended in .md.docx that needed to instead end in -v1.docx. Here is the process I used to easily rename them.

In Emacs, use M-x dired to open the directory.
Use C-x C-q to run dired-toggle-read-only.
Use M-% to run query-replace, and replace .md.docx with -v1.docx.
Finish “writing” the directory with C-c C-c.

All done! It was nice and simple. The DOCX files were finally properly named and ready for review.

Erik L. Arneson — Writer and Software Developer

Writing and Reviewing Jupyter Notebooks

Renaming files with Dired