# [IPython-dev] first experiment creating Software Carpentry teaching materials using the IPython Notebook

Greg Wilson gvwilson@third-bit....
Sat Mar 23 13:36:16 CDT 2013

Hi everyone,

I know it's bad form to introduce myself to a list with a post of this
length, but I just spent a few minutes converting a small part of the
Software Carpentry instructors' guide [1] to an IPython Notebook [2].
Here are a few notes; Paul Ivanov has already opened a ticket [3]
about the linking issue, but I'd be really grateful for your comments
on the rest of it as well: I'm still a notebook newbie, so I'm almost
certainly either doing things the wrong way, or missing things that
are already there.

Thanks,
Greg Wilson
Mozilla Foundation / Software Carpentry

* I want to put each logical thought in its own cell [4].  This
usually translates into "one cell per paragraph, one paragraph per
cell", but not always: as you can see, I often want a small block of
code in the middle of a thought.  In HTML and LaTeX, I signal this
by marking the second (or subsequent) part of the thought with:

<p class="continue">

or:

\noindent

From what I understand, nested cells will do what I want here; any
idea when they're likely to land in production?

* I want to include diagrams done as SVG images in my notebook [5],
but putting:

<img src="setdict-simple-set.svg" />

inside a Markdown cell doesn't work.  After reading
http://lists.ipython.scipy.org/pipermail/ipython-user/2012-July/010542.html,
I tried:

from IPython.display import SVG
SVG(filename='setdict-simple-set.svg')

but it didn't work either. Matt Davis pointed me at:

![A Simple Set](files/setdict-simple-set.svg)

which does.  Longer-term, though, I want to have cells of type
'SVG', and be able to edit my diagrams in-browser using something
like svg-edit.  Fernando and Brian tell me it's not going to make
sense to start work on that 'til mid- to late summer, so for now
I'll use LibreOffice to draw an SVG and then link to an exported
image.

* Part-way through building the notebook, I decided I wanted to
reorder a couple of things, but just moving the cells around didn't
have the desired effect, because the things in question had side
effects [5].  Is there a way to say, "Re-set the In[*] counter to 1
and re-run all cells in the current order"?  (I know I can restart
the kernel and run all, but I don't feel I should have to quit the
editor to renumber things.)  The closest I could get without a
restart was to select the first cell and re-run it and all
subsequent cells manually; that put everything in the right order,
but of course now the numbering starts with '20' instead of '1'.

* What's the right way to link from one notebook to another?  A
Markdown URL of the form:

[displayed text](otherfile.ipynb)

doesn't work, even when otherfile.ipynb is in the same directory.
Reading the discussion around [3] regarding hash URLs, redirection,
etc., it looks like this may already have been solved...

...but how do I link to an anchor in a particular notebook file?
For example, up near the top of the notebook, you'll see the words
"design pattern" formatted as a link.  Right now, the URL in thatl
link is "glossary.ipynb#design-pattern", i.e., the glossary's
definition of the term.  I _could_ use a plain old HTML file for the
glossary (since it isn't likely to have any live content), but I'm
definitely going to want cross-reference links from one section of a
real notebook to a particular section of another.

* I want subscripts (low priority) and tables (high priority) in my
Markdown.  Karthik, Erik, and Paul tell me I have to use HTML tags
for this, which is OK I guess, but from both an editing and a
teaching point of view, it would be _really_ nice if the notebook's
Markdown was identical to GitHub's.  On Twitter, Matthias pointed
out that doing this would be more complex than it first appears,
since things like the Emacs mode would have to be updated as well.

* Cell 37 contains:

import sys

filename = sys.argv[1]
source = open(filename, 'r')
atoms = set()
for line in source:
name = line.strip()
atoms.add(name)
print atoms

I want this pretty-printed as Python, but do _not_ want the notebook
to try to execute it, because I'm not launching it from the command
line.  Can I do that?  And similarly, if I want to format cells to
look like shell commands and their output (and then populate them
with copy-and-paste), can I do that?  I realize it's contrary to the
"lab notebook" philosophy, but pedagogically it's very useful. (And
yes, I _can_ use plain old Markdown cells, but I'd like the colorizing
to be done automatically and consistently.)

* Related to all of the above: I want some way to mark specific cells
with classes.  For example, I want the 'Understand' and 'Summary'
cells to be distinct from regular paragraphs, and the cell starting
with the title 'Negation' to be marked as a callout box, so that I
can give it a border (and maybe a faint gray background) via CSS.

More importantly, I want to be able to mark notebook content as
being:

1. slide
2. presenter's notes
3. pedagogical metadata

The first is what the instructor would show learners while teaching.
The second is the narrative about that (e.g., the paragraphs of text
in the sample notebook in [2]), while the third is things like the
learning objectives (the section marked "Understand" at the start),
which might never be presented to learners, but helps instructors
make sense of it all.  (I _could_ keep these all in separate files,
but experience shows they're much more likely to stay in step if
they're side-by-side.)  Once they're marked with classes somehow, it
should be almost trivial to implement show/hide buttons so that
authors can toggle between "here's what I want learners to see at
this point" and "here's what I want instructors to know about the
same material".

[1] https://github.com/swcarpentry/guide.git + setdict.html

[2] https://github.com/swcarpentry/guide.git + setdict-1-sets.ipynb

[3] https://github.com/ipython/ipython/issues/3056 and
https://github.com/ipython/ipython/pull/3058

[4] It makes things a _lot_ easier to move around during editing.

[5] For the curious, the two things in question are now shown as cells
35 and 36; the original HTML page showed 'clear' before 'remove'
instead of 'remove' before 'clear'.



More information about the IPython-dev mailing list