If you are like me you prefer a readable, aesthetically pleasing structure bit of code to rip off and make your own. Ahhh, I mean use as a template. But sometimes, especially when I first started out, I found I was discouraged from trying to understand what the author had by the hostile looking script they had produced. If I asked for help when I was really struggling I would get shown this sort of thing and die on the inside.
I tried a few different IDEs and was flailing. About 6 months into learning how to program I came across iPython now known today as my beloved Jupyter Notebook. #Jupyter4Lyfe
What was this clear, intuitive and aesthetically pleasing sorcery? I played about and was an immediate convert. I now write my students’ assignment instructions in Jupyter and really wish other lecturers would adopt this practice rather than handing out instructions (you know who you are). But I digress.
I have had ‘real’ programmers scoff at me for not using a ‘real IDE a few times’. I laugh at them because screw linux and sublime. By using Jupyter I know I will be reaching a large group of people who aren’t programmers by trade and will now be able to get a transparent overview of what’s been done. Also, unless I’m doing a Github commit, I can’t be bothered with readme files until I am finished. I prefer to keep notes in the notebook.
Anyway, I love love love Jupyter Notebooks. But as I have started doing experiments requiring non-linear runs (changing what pre-processing strategy I am using for example) I find I have to write really long scripts. So I wanted to find a way to find the sections I am after without having to do a million scrolls. And so entered the humble dynamic table of contents (TOC). This is the magic of a TOC. Side note, if you are allowed to submit assignments in Jupyter, do it and install a TOC. Your tutors/ lecturers will thank you. Make their job easy and they will be inclined to give you a good mark.
The Magic
Before we start, I am a Mac user and so use bash (Bourne Again SHell). Windows users will use cmd.exe and Powershell. If you are a window user I am so so sorry for your loss, your loss of assessing to 95% of your OS capabilities. So for Windows users, step one is get a mac.
Install pip
Mac users head to this pretty walkthrough to install pip.
Windows users head over here to install pip.
Installation of nbextensions
Alright, the jupyter_nbextensions_configurator is a type of extension that beefs up the capabilities of Jupyter and adds new buttons for formatting, adding enhancing functions etc. to the interface you see in Jupyter. After you add this extension it will load automatically and you won’t need to reset it every time. There are so many options in the nbextentions configurator that we will go through in another article but if you want all if the info, as always, read the docs.
If you are a conda user
In your terminal or cmd, type the following:
conda install -c conda-forge jupyter_nbextensions_configurator
If you prefer pip
I prefer pip, but there are two steps to nbextensions than conda.
Step 1. Install the pip package by copying this into your terminal or cmd.
pip install jupyter_nbextensions_configuratorStep 2. Configure the notebook server to load the extension.
This is done with something called a Jupyter sub-comand which just tells the actual notebook to install the server extension, kind of like when you use ‘import some-package’ in your note book after you have done ‘pip install some-package’ in your terminal or cmd. Now copy and paste this in:
jupyter nbextensions_configurator enable --userYou will get something that looks like this:
Choosing your options in your brand new nbextensions panel
Now open up a new jupyter notebook and you should see a new option called Nbextensions.
Click on the panel and check the Table of Contents (2) and toc/loc configurations. Like this:
Collapsing Sections
Before you start, I recommend ticking the collapsible headings option as well. It’s the fourth from the top of the first column of options. You will see why shortly.
Ok, we are ready to go. Open up a new notebook and enable table of contents. Like this.
Then you will need to so some little configuring of the ToC2 settings. When you click on the TOC button you will see a sidebar on the left-hand side called ‘Contents’ it will have a refresher icon and a settings icon. Click the settings icon. Then enable all of the settings you want.
I recommend all of these, particularly the ‘Leave h1 items out of ToC’ checkbox. Otherwise, you will a number 1 next to your TOC which looks bad and throws off the numbering.
Getting a TOC in your notebook
To put in your first heading, set the cell to markdown and then use two ‘##’ to call a main header.
To put in a subheading user three ‘###’.
You can keep putting in sub-headers with up to five ‘#’ so that you have four levels of sub-headings like this.
And there you are, automatically generated TOC in your notebook.
Related features
Colour coding
You will notice that the TOC is highlighted here in yellow. This indicates where you are in your notebook. When you run a cell this the section that a that cell is running will turn red. Here is an example:
This is pretty handy when you are running code that takes a while and you are messing about with something else in the notebook.
Navigator and Sidebar
Go up to your main set of tabs where File, Edit, View etc. Click on the ‘Navigate’ tab. You will have to expand the box to see the contents which you can click on. This option isn’t one I use too much because I like the sidebar. Speaking of the sidebar, you can move it around to wherever you want it to be.
And that’s it. You now have TOC which will make your work more easily navigated, and anyone you distribute the notebook will be happy that the TOC is in-place regardless of whether they use these extensions.
If you got something out of this walkthrough we would love if you could spread the work. Twitter is a great way to do this.
Credit to Bundo Kim for the amazing feature photo. For more of Bundo’s work please head to unsplash @bundo
The Little Data Scientist 