Update 26 October 2015: The ipython-extensions repository has been updated with instructions for Jupyter/IPython 4.0, but for now, the CodeMirror customizations do not seem to work.
Update 4 March 2015: As of IPython 3.0, it seems that code in custom.js (such as the examples below) should be attached to the app_initialized.NotebookApp event (the ipython-extensions repository is updated accordingly):
$([IPython.events]).on("app_initialized.NotebookApp", function () {
// your code here
});
Since I use the IPython notebook for a lot of explorative data analysis, I wanted some extra functionality to make day-to-day notebook work just a little bit more pleasant. I use several of Min RK’s excellent notebook extensions, particularly the floating table of contents and the Gist button.
This post describes some additional extensions I created to do things I need in day-to-day work, as well as how to leverage the customization possibilities of the CodeMirror editor to add vertical rulers to code cells. The notebook extensions described here are available on GitHub.
Notifications
Sometimes larger analysis tasks take more than a couple of seconds to compute, and I want to alt-tab to do something else while I wait. The IPython-notify extension ensures that you don’t forget what you were originally doing, by displaying a notification once the kernel becomes idle again after a set minimum busy time:
When the plugin is activated, a button to request notification permissions is shown in the toolbar. After notification permissions have been granted, this button is replaced by a dropdown menu with five choices: Disabled, 0, 5, 10 and 30.
To activate notifications, select a minimum kernel busy time required to trigger a notification (e.g. if selecting 5, a notification will only be shown if the kernel was busy for more than 5 seconds). The selection is saved in the notebook’s metadata and restored when the notebook is re-opened.
Theme switching
As described in a previous post, depending on ambient lighting and time of day I prefer seeing my code in light text on a dark background, so I created a simple extension to switch between two themes.
The default CSS included only changes code cells (this has the added effect that it’s easier to tell code cells apart from markdown or raw cells):
The CSS files can easily be exchanged for a different ones, for example a Base16 theme.
Customizing the CodeMirror editor
IPython notebooks use the CodeMirror editor, which includes a wide range of addons. IPython also allows the user to add additional javascript and CSS via the custom.js and custom.css files in the static/custom directory inside the IPython profile (likely ~/.ipython/profile_default/static/custom on Linux or OS X).
I want to display some rulers to indicate line lengths I shouldn’t exceed to conform with PEP8. Thanks to CodeMirror’s flexible configuration system, this can be achieved by adding the following code to custom.js, making use of the rulers addon:
require(["components/codemirror/addon/display/rulers"]);
var clsname = "ipynb_ruler";
var rulers = [{column: 79, className: clsname},
{column: 99, className: clsname}];
IPython.Cell.options_default.cm_config.rulers = rulers;
By adding the class ipynb_ruler to custom.css, the look of the rulers can be tweaked, for example to use a lighter color:
.ipynb_ruler {
border-color: #DFDFDF;
}
Unfortunately, there is a bug in older CodeMirror versions that in some browsers causes extra scrollbars when enabling rulers. For the time being, this can be fixed by placing a fixed rulers.js into ~/.ipython/profile_default/static/components/codemirror/addon/display (adjust as needed if your IPython profile directory is different). I backported a fix into the rulers.js shipped with IPython 2.2, available here.