pysal / geopyter Goto Github PK

What metadata do we need to track about each notebook?

1. How long each section should take
2. Difficulty level
3. Authorship
4. Git status

Ideas from software carpentry web site?

Ability to import answers/code after the fact?

E.g. if you don't give 100% working code how do you manage changes over time?

Evidently, nbconvert is unidirectional going from the ipynb format to a host of other formats. It does not handle conversion to ipynb from these other sources.

The package notedown does handle the case of conversion back to ipynb from markdown.

Example of conversion to Markdown

$ notedown choropleth.ipynb --to markdown --strip > output.md

Creating a notebook from a Markdown file

To create a notebook from the converted file do:

$ notedown output.md --run > output.ipynb

Then start the notebook browser as usual.

Manipulating the converted md file

I was able to take the output.md file created above, and go in an delete a range of cells (by hand), saving the file as output_trim.md. This can then be run with:

$ notedown output_trim.md --run > output_trim.ipynb

Next Steps

If we can develop the syntax for section/subsection identification/skipping/including, this should mean automated generation of new md files from atoms becomes feasible.

Flesh out the syntax for identification of

• resource
• elements of resource to extract

Have to consider

• cell type for the @include
• do we include options for omitting output of cells
• other?

Enforce data set consistency within atoms -- So we should use one data set for all of the atoms in one group and then, say, a different data set for the ML.

Prototyping is being done in Python 2. We should support both 2 and 3

Build a TOC interface to makes things selectable? Seems like two kinds of interaction: 1. Having a catalogue from which you can select interactively; 2. Having a conf file that just runs without your having to provide any input when you want to rebuild the lesson.

Also, want to think about tracking the commit version so that all compiled notebooks are stable unless you choose to update them -- idea being that your practical doesn't get clobbered because you weren't aware of a change to the content.

I don't think we ever got around to implementing the use of remote notebooks, which would obviously be a rather useful feature since it saves the user even having to download/clone notebooks from GitHub! Behind the scenes we can always download to a local tmp directory in order to pass the data to our processor, but the user doesn't need to know that.

So something like:
@include {
'nb' = 'https://github.com/kingsgeocomp/code-camp/blob/master/notebook-02.ipynb'
}

The only downside I can see to this is that if you want a particular version you can't use a branch without changing the URL... but I think you can still use tags that are on the master right? So we could still (I believe) write:

@include {
'nb' = 'https://github.com/kingsgeocomp/code-camp/blob/master/notebook-02.ipynb',
'tag' = 'v1_2', # Note, doesn't exist, just for illustrative purposes
'select' = 'h1.Understanding Lists'
}

from @jreades

Currently we use 'resource' as the keyword inside the @include statement. That seems a rather wordy parameter name to me and I was wondering about 'nb' as an alternative that is also consistent with the terminology used by other utilities (nbconvert, etc.) that work with Jupyter notebooks.

Discovered that if you have more than one hit on an exclude (e.g. -h4.A challenge for you!) then it will exclude the first but not check for a second hit.

Separation of concerns to have a module(s) to handle manipulation of notebooks.

Should support recursion, but not encourage it. I.e. no reason why an imported file can't, itself, contain imports, but we should suggest that atoms don't import. That's why they're atoms.

Use travis for testing on changes to the atoms/content

Set up nightly testing to capture bugs induced by library version bumps