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

Sat Mar 23 15:26:34 EDT 2013

Hi Greg, 

I'll respond to a few of your question inline.

Le 23 mars 2013 à 19:36, Greg Wilson a écrit :

> 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?

Probably in the next 2 years. But not soon. We can try to work around that with
custom js extension and cell toolbar (cf below for custom cell marking)

> 
> * I want to include diagrams done as SVG images in my notebook [5],
>  but putting:
> 
>  <img src="setdict-simple-set.svg" />

you miss the files/ prefix :-)

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

This is strange...

> 
>  but it didn't work either. Matt Davis pointed me at:
> 
>  ![A Simple Set](files/setdict-simple-set.svg)
which should be converted to <img src="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'.

No, not possible, you could write js that does it, but the In[] and Out[] represent kernel state.

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

We know about that, Min opend a PR a few hours ago, I'm just concern on how it will integrate
when we add the ability to browse filesystem. 

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

The anchor are another problem, we are working on it too.

> 
> * I want subscripts (low priority)

use Mathjax ? $H2_O$ ?

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

I agree that table would be nice too, and some of github feature also like (triple-backquote-language) to select coloration. 
It is just too much to handle in the core for now. If/when we have more manpower, that would be great. 
Still you could, with an extension, make the table from python code.

> 
> * 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?  

4 space indent in MD cell should convert to "code" environment in markdown.
Not sure if it colorize, there is also the problem of multiple language...
GFM could help, but back to manpower question, and the fact that GFM 
is done on server side, our on browser side. 
One can also use "raw" cell and force the coloring via js extension. 

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

With extension, you could "lock" some cell. But the extension have to be install on student notebooks. 

> 
> * 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".

That's on dev version. Arbitrary marking cell with tag in metadata and a custom custom.css. 
That will probably not be shipped with IPython, but you could ask user to use an ipython "teacher"
profile or "student" profile. It should even not be hard to generate multiple ipynb from master one. 

Also those metadata are what is use to make the live slideshow mode of notebooks. It has apparently been used
in conferences not so long ago by Fernando I think , did you saw it ? I think it is also in his talk of SciPy "12.

This could add options like lock cell, hide cell, add class to cells...
as long as the correct js is loaded/monkeypatched. 

Depending on how you want to display the different things and/or if you want to convert 
your ipynb files to static views/ pdf ...etc you might also need to add plugins to nbconvert.
Should not be difficult.

I wrote a nbviewer post [6] about what cell toolbar can do, it might give you idea on how to do some stuff. 

-- 
Matthias

[6] http://nbviewer.ipython.org/urls/raw.github.com/Carreau/posts/master/04-initialisation-cell.ipynb

> 
> [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'.
> 
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev