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

[Greg Wilson]

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'.