[IPython-dev] first experiment creating Software Carpentry teaching materials using the IPython Notebook
Sat Mar 23 13:36:16 CDT 2013
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  to an IPython Notebook .
Here are a few notes; Paul Ivanov has already opened a ticket 
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.
Mozilla Foundation / Software Carpentry
* I want to put each logical thought in its own cell . 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:
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 ,
<img src="setdict-simple-set.svg" />
inside a Markdown cell doesn't work. After reading
from IPython.display import 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
* 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 . 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:
doesn't work, even when otherfile.ipynb is in the same directory.
Reading the discussion around  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:
filename = sys.argv
source = open(filename, 'r')
atoms = set()
for line in source:
name = line.strip()
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
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 ), 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
 https://github.com/swcarpentry/guide.git + setdict.html
 https://github.com/swcarpentry/guide.git + setdict-1-sets.ipynb
 https://github.com/ipython/ipython/issues/3056 and
 It makes things a _lot_ easier to move around during editing.
 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