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 project now fully supports building:
- Jupyter Notebooks (IPYNB)
- Websites (with download notebook and pdf support)
- 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
Once setup; running
make 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
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 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.