Generating reports for Jupyter notebooks


#1

In Deploying JupyterHub for Education @lawasser made a nice description of what she’d want out of a “report generation tool” for Jupyter notebooks. I wonder if this is a specific enough and common enough issue to warrant its own thread here, in case others would like to chime in.

From her post, it sounds like there are a few things that you’d want to go from notebook -> HTML report.

  1. Export to HTML or PDF, doing the following things:
  2. Hide things in the final report. E.g., metadata in a cell should selectively remove things like:
    • The stderr
    • Image outputs
    • Code blocks
  3. Strip input/output numbers, or anything that is unique to the “interactive” session vs. just the cell contents and outputs.
  4. Do some fancier things with some cells (such as adding captions to images).
  5. Make the output pretty to look at.

What else would be important? Most of those things I think are pretty doable (the one exception being how far down the rabbit hole you’d wanna go creating new features for #4 ). Perhaps we can get a nice design spec on a tool that would be useful! I’m thinking it could be a ‘bundler extension’ which basically just means a new option under “Download as” that’d output a nicely-formatted HTML file


#2

That would be a cool way of exposing this. I think most of the requirements can be achieved with nbconvert + a new HTML template. This means that the “hard” part is making it accessible to people who don’t know how to construct their own template and making it “configurable” through the existing notebook (classic and lab) interface.

  • Do bundler extensions work in lab as well?
  • Could we use tags as a way to expose the choices to users?

#3

I threw up the code from that GIF into a little python module here:

Worth iterating on? It’s pretty lightweight so would be easy to extend, modify, etc.

re: your questions, I think that bundler extensions should “just work” with lab (at least, it seemed like bundlers were a way to abstract away the concept so that it wasn’t notebook-interface-dependent).

re: tags, yep that’s what I’m imagining. nbreport already uses the presence of some tags to choose what to do with cells. You could also use metadata for the cell to add stuff like caption:"my caption"


#4

@choldgraf just a note about how rmarkdown works and how you could keep this simple!
For jupyter notebooks, i’ve added a caption tag to the jupyte template
The code is as follows:

{% block data_png %}
<figure>
{% if cell.metadata.caption %}
<img src = "{{ output.metadata.filenames['image/png'] | path2url }}" alt = "{{ cell.metadata.caption }}">
<figcaption>{{ cell.metadata.caption }}</figcaption>
{% else %}
<img src = "{{ output.metadata.filenames['image/png'] | path2url }}">
{% endif %}
</figure>
{% endblock data_png %}

it relies on a caption metadata input. This could be build into a sweet notebook cell interface like what hide_code has to be easier to add… it produces a caption like you see on this page when built:

Here is the beauty of this all. if you publish to HTML and also allow a user to specify a css style sheet now… WALLAH you have beautiful customization at your fingertips :slight_smile:

I LOVE YOUR suggestion of a download_as implementation. so much easier than having to make a special button that might not work. I would also love to be able to run it at the CLI!
Please let me know how i can help with this effort. students would LOVE IT. and so would anyone doing reproducible work who might write a paper or just a report in this envt in the future.


#5

I love it! My only question is: why isn’t there a “try it on binder” badge in that repo? :smile:


#6

I had one last thought. One thing about rmarkdown that makes it flexible is having the yaml header at the top. I suppose on one hand this clutters up the file at the top. On the other you can easily add new element if you wish. They use that to provide a css file that will style the output html file. they also use it to add functionality like bibliographies, etc. Not sure if this is ideal vs storing things in the first cell via the metadata… but just wanted to chime in as providing the ability to customize a report using a standard approach is nice .


#7

OK there’s a proof-of-concept Binder here: https://mybinder.org/v2/gh/choldgraf/nbreport/master?filepath=example%2Fan_example_notebook.ipynb try going to File -> Download As -> NBReport. It should generate an HTML file in the same folder as the ipynb file.

btw: thanks for the suggestion on the caption! feature added to nbreport :slight_smile: