Introducing Jupinx
Generating Jupyter notebooks from text files
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 Sphinx extension that converts reStructuredText files (RST files) into Jupyter notebooks.
The Jupinx tool was specifically built to help us better maintain our suite of online lectures and will eventually allow users of the site to download Jupyter notebook versions of our content. 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 (note that at the moment, only Python and Julia code blocks are officially supported). Text in the RST file is converted to Markdown and displayed in Jupyter’s Markdown cells. Once the Sphinx extension is installed and added to the conf.py file, running make jupyter will produce a Jupyter notebook file (.ipynb) containing both code and text (or code-only depending on your settings).
Why use Jupinx?
The main reason we wanted to build Jupinx was so that we could easily version control Jupyter notebooks. Jupyter notebooks are essentially JSON files which, in raw format, are difficult to interpret and as a result, difficult to 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 sphinxcontrib-jupyter. Instructions on how to use the package can be found on the page’s README.
Future development and how to contribute
We would like Jupinx to fully support more languages outside of Python and Julia, in addition to a wider set of the RST markup specification. We’re also working on a command line tool for direct translation between a single RST source file and a compiled Jupyter notebook. This would make working with RST files as a source a bit more agile without the complication of having to compile within the Sphinx framework.
If you’d like to contribute to the project, please check out the issue tracker to find tasks or make suggestions. We encourage you to head to our Discourse forum if you have any questions, or email us at contact@quantecon.org.
Acknowledgements
Jupinx was developed by Matthew McKay, 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.
