[IPython-dev] first experiment creating Software Carpentry teaching materials using the IPython Notebook
MinRK
benjaminrk at gmail.com
Sat Mar 23 15:49:25 EDT 2013
Thanks for all the feedback! Comments inline.
On Sat, Mar 23, 2013 at 11:36 AM, Greg Wilson <gvwilson at third-bit.com>wrote:
> 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?
>
We have no plans for nested cells per se. Our current plan for expressing
document hierarchy is strictly with header cells, and operating on the
groupings implied by these headers - outline view, tabbed view, reordering
/ hiding whole sections at a time, etc. One case this really doesn't serve
is the code cell inside a paragraph case. We'll have to think about this
one.
>
> * 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:
>
> 
>
I'm a bit confused by this - your notebook currently has
SVG(filename='setdict-simple-set.svg'),
and seems to be working properly. Is it not?
>
> 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.
You can have SVG inlined in a markdown cell already, but an SVG-edit widget
would still be useful.
>
> * 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'.
>
Prompt numbers are strictly and deliberately side effects of running cells.
If you want to reset without restarting, you can call `%reset` before doing
'run all'.
I do not think that we are going to provide a mechanism for making any
direct change to prompt numbers (other than clearing them).
What do you mean by 'quit the editor'? Are you doing this outside the
notebook?
>
> * 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.
>
In theory, a regular anchor url should work (we don't generate anchors, but
we should for things like header cells, at least) but it doesn't seem to.
I haven't investigated thoroughly, but my guess is that it's because the
elements in the page don't actually exist when the anchor url is resolved,
as the notebook document is loaded asynchronously.
I bet we can figure this one out, though.
in-page anchors should actually work already (barring the fact that IPython
doesn't add any itself yet, but your own anchors should work).
So things to add here:
1. when we render heading cells, give them the attr name=heading
2. investigate scrolling to anchor in url on the 'notebook loaded' event
actually, I did it before I finished this email:
https://github.com/ipython/ipython/pull/3064
>
> * 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.
>
We are extremely reticent to extend the markdown syntax,
because maintaining such a thing is well outside our core competency.
We have already found this to be troublesome with our one extension so far
- including mathjax.
*However*, tables are a part of GitHub0-flavored markdown,
which all of us use every day.
So perhaps we can get away with finding a javascript implementation of GHM,
in which case you would get tables as described
here<https://help.github.com/articles/github-flavored-markdown>
.
>
> * 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.)
>
If you indent a block four spaces in a markdown cell, it will be
highlighted as code, but is not a code cell,
and thus will not be executed. This mechanism uses `prettify`, which
infers the language being used,
and should highlight Python and shell blobs scripts properly.
>
> * 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.
>
The API for this would be cell metadata - in master, activate the cell
toolbar to edit metadata for each cell.
We need to figure out some mechanisms for what we do with cell metadata,
and what we let authors do with metdata in terms of UI and effects.
The very best information on this is use cases people need, so we will
definitely keep this in mind as we work out the design.
>
> 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'.
>
Thanks again!
-MinRK
>
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20130323/72621208/attachment.html>
More information about the IPython-dev
mailing list