Image for post
Image for post


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.

Image for post
Image for post
Example of using Jupinx to convert RST to a Jupyter notebook

Why use Jupinx?

Image for post
Image for post
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

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store