Matt McKay
Dec 4, 2019 · 3 min read

Generating Jupyter notebooks from text files

This article is an updated version from the original article introducing sphinxcontrib-jupyter. The extension can now generate Jupyter Notebooks, construct websites, and build PDF Files. There is also a jupinx command-line utility now available too.

Do you prefer LaTeX to MS Word? Of course you do. And the reason you do is that LaTeX uses text files for editing and generates its output.

After all, who doesn’t love text files? Gloriously simple, ready made for your favorite text editor and perfect for version control.

We at QuantEcon share your views. So, being the good, fun loving and thoughtful people that we are, we’ve built us all a new tool called Jupinx. Jupinx is a command line utility that makes it easier to setup projects that use the sphinxcontrib-jupyter extension that converts reStructuredText files (RST files) into Jupyter notebooks.

The Jupinx family of tools was specifically built to help us better maintain our suite of online lectures. Our Quantitative Economics with Python lectures is an example of what it can do.

The project now fully supports building:

  1. Jupyter Notebooks (IPYNB)
  2. Websites (with download notebook and pdf support)
  3. PDF files (individual RST files and book style PDF files)

Jupinx is open sourced on GitHub and contributions are welcome.

How it works

Once setup; runningmake jupyter will produce a Jupyter notebook file (.ipynb) containing both code and text (or code-only depending on your settings). You can also use the quickstart to build html and pdf files.

Example of using Jupinx to convert RST to a Jupyter notebook

Why use Jupinx?

Jupyter notebook displayed in a text editor

By writing our lectures in RST format and using Jupinx to build Jupyter notebooks, we can maintain our site while also easily testing out edits to code. Before pushing any edits to our lectures, we use Jupinx to build the edited notebook and test that it executes.

If you’re looking for a way to track changes in Jupyter notebooks directly, you could also consider nbdime, a toolbox that that allows you to compare and merge Jupyter notebooks. This is a useful git extension for those who would like to maintain a set of Jupyter notebooks directly. We find editing RST to be easier in our day to day work.

Where to get Jupinx


QuantEcon Blog

Open source code for economic modeling

QuantEcon Blog

Open source code for economic modeling

Matt McKay

Written by

QuantEcon Blog

Open source code for economic modeling