Why should I care?
I think it's kind of cool that you can write text beside snippets of code that actually run and automatically have the output of your code display alongside it.
Say I want to describe a function that plots a sine wave at different amplitudes.
import matplotlib.pyplot as plt import numpy as np def plot_sin(amplitude=1): '''Plot a sine wave of a given amplitude''' time = np.arange(0, 10, 0.1) y = np.sin(time) plt.plot(time, amplitude*y) plt.ylabel('Amplitude') plt.xlabel('Time (s)') plt.show()
Then, just after defining it, I could call it with different arguments and display the outputs alongside any text.
All of the above was written and ran within a Jupyter Notebook and automatically formatted for this blogpost. I didn't have to have some scripts lying around to create the images in the post. I didn't have to save, upload and link to the images. I didn't have to worry that the code examples wouldn't run.
You can also paste images as you would expect.
It's a mix and match of a few different tools.
- Jupyter Notebooks
- Github Pages
The Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and narrative text.
The repo was first created from the fast-template repo from fast.ai's Jeremy Howard. This is a simplified way to generate a blog and host it using Github Pages. You can write your posts in Markdown Language and when you commit them to your repo, they will be converted to html for your blog using Jekyll.
nbdev is a really powerful library which isn't being used to it's fullest potential here. It's a tool to create entire python libraries, a website hosting your documentation and way to automatically run tests... all using Jupyter Notebooks.
But for this project, it's being used to export output cells and any uploaded attachment from Jupyter Notebooks to markdown using
nbdev_detach *.ipynb and
nbdev_nb2md to convert notebooks to markdown. It's also being used to remove metadata from the notebooks during git commits, which helps reducing the change of merge conflicts. That last feature is probably overkill because I don't think I'll be doing a lot of merging.
Last but not least, Github Actions runs all of the above during each commit automatically! See here for the config. This is mostly taken from nbdev with a few things changed.
A huge thanks to Jeremy Howard at fastai for making fast-template and nbdev which is doing all of the hard work to bring all these tools together!