Support for Jupyter Notebooks

[mahiradayal]

I would like bottlejack to support ipynbs

[jsoma]

Seems like it could be useful, but how do you want to use Jupyter noteboks?

It might be useful to start from thinking about how we could adjust the gdoc type, which currently looks like this:

  - type: gdoc
    title: this is the first project
    slug: first-project
    url: https://docs.google.com/document/d/....

Some questions for this proposal might be:

• What would the pages yaml look like for a Jupyter file?
• Where would the .ipynb files live? Can they be anywhere on my computer? In a specific folder?
• Instead of adding each notebook individually to 'pages', maybe we should automatically process all ipynb files that live in a specific folder instead?

It's probably useful to think about it in connection to #3, too. Should they operate the same way?

[AFarence]

How's this:

type: ipynb
title: this is the methodology for the first project
url: file path to notebook (or HTML file?)

Where I think I'm lost, and what I think we want to happen, is effectively have bottlejack covert a jupyter notebook into an HTML file - perhaps according to the stylization of each cell? (For example, the #heading format might convert to <h1>, and markdown might convert to the default style of the <p> tag.

I don't think we need to add each notebook individually. It would be must easier to process an entire folder at once, have those files show up in data.yaml, then we can link as needed.

[shane-burke]

Thinking about it, I feel like the ipynb would still have to be divided into divs/tags/classes/etc. to be styled in a useful way. That makes me think that saving the ipynbs as HTML files like we did and maybe just assigning certain CSS stylesheets to the entire file might work better when uploading ipynbs alone with bottlejack.

Different areas we would have to code as individual divs are the boxes, differentiating inputs and outputs and any messages from the system. I don't think the format has to be too flashy: if we're posting it, it's either because there is a cool output for a dashboard or because we just want to prove we can code/have someone check against our code.

[jsoma]

I think for the immediate moment your best bet is to use pandoc to convert a notebook to HTML, and then use it with the html page type:

pandoc your-notebook.ipynb -o output.html

Or export as HTML directly from Jupyter, but I don't think that looks nearly as nice.

[hc3188]

What's the best way to include a text walk-through of the notebook? I'm inclined to add it via markdown in the notebook, as opposed to trying to add text in the home files.

[jsoma]

Yep, I agree! Definitely just add markdown sections to the notebook. Alternate between markdown blocks and code blocks, stepping through what you're doing, and then just convert to .html via export or pandoc.

[mahiradayal]

@jsoma I'm having a hard time using pandoc. Is there a walkthrough or useful documentation for reference?

pandoc your-notebook.ipynb -o output.html This did not work for me so I downloaded HTML files straight from Jupyter as placeholders.