Jupyter Notebooks: Sharing your Work
We primarily use Jupyter for development & exploration work. But the Jupyter ecosystem has now evolved to make it easier to share your work as well. We share our Jupyter work mainly in these contexts:
- Libraries: For developers within and outside your team
- Publish Blogs & Books: For data professionals and developers
- Notebook Experiments: For teammates to review and discuss
- As Apps: For non-programming stakeholders e.g. analysts and Product Managers
Let’s go through all of these contexts and discuss best tools for each.
Writing Libraries
nbdev
The newest nerd kid on the block is nbdev from fast.ai. nbdev is a library that allows you to develop a python library in Jupyter Notebooks.
No longer going through that grind of first experimenting in a notebook and then painfully writing and organizing a Python file which others can import and use.
It automatically generates docs for you, and hosts them on Github Pages. It also has utilities which makes it easy to publish packages on PyPI.
It syncs your changes to and fro from the .py files you’re exporting to. Making it easier to do quick changes in the code when needed, but continuing to use Jupyter as your main IDE.
Using comments like #export, you’ve control over what you want in your sync’ed .py file. It works across both Jupyter notebooks and JupyterLab.
Jupytext and nbconvert
Jupytext and nbconvert are quite similar in spirit. They allow you to convert your Jupyter notebook into a different format. The target formats could be code (Python, R, Julia), markdown, pdf, html and several more.
Lot of static publishing tools like Jekyll and Hugo use Markdown to write your posts and work natively with Github Pages. The pdf format is quite useful if you’re looking to share your work with explanations and diagrams with someone non-technical.
nbconvert is a one way conversion: It simply converts your notebook from .ipynb to your target format. Jupytext is more powerful and allows you to sync back changes from a target format e.g. code or markdown back to the notebook using something called paired notebooks.
Nbconvert is most commonly used as a command line tool. Jupytext is configurable and accessible via your JupyterLab interface.
Blogging & Publishing
nbinteract
nbinteract is an extremely powerful publishing tool. Most commonly used for illustrating simulations, user-guided data explorations and interactive reports.
Directly from their docs:
nbinteract is a Python package that provides a command-line tool to generate interactive web pages from Jupyter notebooks. It allows Jupyter widgets to remain interactive even when the notebook is converted to static HTML by using Binder servers as the computational backend.
This means you can strike a fine balance between publishing static web pages of your results, explanations and code - but retain the Jupyter widgets functionality which enables powerful, interactive demos.
Jupyter Book
JupyterBook is quite a nice way to bundle your notebooks and publish as an HTML, Markdown, pdf or similar.
It automatically does some of the heavy-lifting around typesetting and organisation for you. E.g. Table of Contents is auto-generated and navigation across “chapters” is set up. With Github actions, you can enable publishing on every push (example: NLP Quickbook). This makes it best suited for writing technical books.
You can even add commenting and highlighting by turning on Hypothes.is for your book. The scikit-learn MOOC is an excellent example of a modern Jupyter book.
Fastpages
The starting point here is as simple as forking the fastpages repo. It uses Github Pages, Github Actions and Jekyll - so that all your changes in a notebook are automatically published. Since the blog is ultimately pushed via Github, you can even ask friends or people within your team to review the blog before you publish using ReviewNB.
Fastpages is also quite versatile as it also allows you to write blogs via Word Docs and Markdown in addition to Jupyter (example: here). It has a neat index page which is HTML and editable, if you want to execute any tracking scripts like Google Analytics.
Sharing Notebooks with Team
The two most important features for sharing notebooks with your team are:
- Ability to discuss and comment
- Access control
JDoc
JDoc (Jupyter Doc) is a ReviewNB feature which gives you a Google Doc experience for Jupyter Notebooks. You can write comments on any notebook cell. As you push new versions of your notebook, it automatically maps those conversations to the correct cell.
It’s ideal for experimental work where the goal is not merge-to-master. This is quite common when you’re doing data exploration or modeling experiments. Your reviewer’s comments are stored safely with ReviewNB and not lost when you delete cells.
The only major limitation is the lack of an executable environment for your code.
Colab
Another way to share your work with teammates is Google Colaboratory. It has inbuilt access control, quite similar to what you’d see with Google Docs. It’s also executable (like Binder), which means that your reviewer can run the code and see it.
But similar to Google Docs, the comments are tightly linked to cells. This leads to some weird edge cases. E.g. you made a comment on an import and then the cell itself was deleted, and the bad code moved to a new cell - the comment is also deleted with that cell.
It has no way to store different versions of your notebook which would’ve been quite useful e.g. if you made a change based on a review comment, your reviewer might like to see before-and-after version & compare the diff.
Interactive Apps
Simple yet flexible interactive apps can be built from within Jupyter notebooks. This gives Jupyter the same power as Streamlit. This mechanism is quite useful for taking inputs from teammates who’re not programmers themselves or sharing the results of a data analysis.
These are quite powerful ways to showcase your work as well as allowing your non-programming teammates to use your work - without waiting on you to run the notebook.
Web App via Voila
Arguably the most powerful of them is Voila. Voila renders an entire notebook as a web app. It converts widgets into executable blocks and static cell outputs to HTML. It’s a great way to share your work with your team.
Voila is arguably also the easiest of the lot to deploy with stable deployment docs across Heroku, Binder and Google App Engine.
Panel
If you find running the same notebook again and again as data gets refreshed every few days, and then exporting the results to someone - you should consider converting your notebook to a dashboard.
Panel makes this quite easy. It supports almost all popular graphing and plotting libraries. It has some neat app-like features which make user interaction smoother.
Say you’re simply exporting your csv or xlsx file for each new input, Panel makes I/O interfaces setup easy - allowing both an input and a download csv option.
Panel runs on Bokeh, which uses a Tornado server. The official Panel docs have a nice guide on how to deploy Panel on Heroku, MyBinder and Azure.
Dash
In the same vein as Panel, but built for and by plotly: JupyterDash converts your beautiful, interactive plots into a dashboard. What Dash lacks in support for other common graphical libs, is compensated by the ease of use - if you’re already familiar with the Plotly ecosystem.
They’ve a gallery of examples for Enterprise users.
Dash Enterprise has deployment options for both on-premise and 3 major cloud providers: AWS, Azure and GCP. For free, public apps they’ve a guide to Heroku deployment.
About Author
Nirant (about) has been doing Machine Learning for over 5 years, in addition to being a published author.
Summary
We discussed a wide variety of tools which makes it easy to share your Jupyter work.
- nbdev helps you build python packages in notebooks
- nbinteract is great at converting notebooks into interactive web pages
- Google Colaboratory & ReviewNB are useful for team collaboration & feedback
- Fastpages is a Jupyter-powered blogging platform
- Voila, Panel and Dash lets you publish notebooks as web apps and dashboards
| Categories | Tools |
|---|---|
| Writing Libraries | NBdev, Jupytext and nbconvert |
| Blogging | NB Interact, Fastpages, Jupytext |
| Book | JupyterBook |
| Sharing with Team | JDoc, Colab |
| Interactive Apps | Voila, Panel, Dash |