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

Jupinx works by taking RST files and moving code contained in code-block:: directives to Jupyter code cells. Text in the RST file is converted to Markdown and displayed in Jupyter’s Markdown cells. The easiest way to setup a new project is to install jupinx and use jupinx-quickstart

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.

Why use Jupinx?

The main reason we wanted to build Jupinx was so that we could easily version control large projects that can also support Jupyter notebooks. Jupyter notebooks are a machine readable JSON file which, in raw format, are difficult to interpret for a human and as a result, difficult to easily track changes.

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

Jupinx is available on GitHub. Users can install the package with pip install jupinx. A tutorial is also available here to get you up and running.


Jupinx was developed by Matthew McKay, Aakash Gupta Choudhury, Akira Matsushita, and Nick Sifniotis. The QuantEcon organization is fiscally sponsored by NumFOCUS. We are grateful to the Sloan Foundation for supporting the QuantEcon project.

QuantEcon Blog

Open source code for economic modeling

Matt McKay

Written by

QuantEcon Blog

Open source code for economic modeling

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade