Voila: Using voila *just* for HTML generation

[choldgraf]

Have folks thought about exposing the ability to use Voila just for generating HTML from a single notebook? E.g., use its templating framework to create HTML reports from a notebook, but that run on their own w/o a Jupyter server under the hood.

I'm thinking about separating out the "build an HTML page from a jupyter notebook" functionality from Jupyter Book, and having Jupyter Book just use a separate package for each ipynb -> html conversion. This made me think perhaps the thing that'd build these HTML files could be voila w/ a few modifications, instead of a new package. I'm curious what folks think about that.

Alternatively, if somebody wants to give me a quick rundown of how the templating setup works, I can try piggybacking on that pattern in a new package. (see https://discourse.jupyter.org/t/generating-reports-for-jupyter-notebooks/279/20?u=choldgraf for some context)

[timkpaine]

What's the benefit over nbconvert/the stuff voila is upstreaming to it.

[choldgraf]

Yeah I agree with your intuition. I just notice that I keep having conversations with people where they ask "why can't I create a nice report from a notebook" and my response is "well you actually can, with nbconvert it's just XYZ flags and parameters".

I think nbconvert is awesome as a general purpose conversion tool with lots of functionality, but I think the api of nbconvert is just too complex to expect individual users to use it for a very specific purpose. I think there's a lot of value in these packages that basically wrap nbconvert and expose a more streamlined api + some extra convenience functionality.

To me one of the benefits of Voila is that it's exposing this pattern for easily adding new themes, templates, etc. Sure, a lot of that stuff was technically possible before, but making it straightforward and easy brings a lot of value, and for many people it's the difference between actually doing it or not. It could be that this particular use-case (static HTML reports from a notebook) is out-of-scope for Voila, but in that case I'd still like to follow Voila's patterns either way in order to reduce cognitive load on people.

I really like the pattern of "nbconvert is fully-featured but very complex, and there are tools like voila, papermill, jupyter book etc that constrain those features for specific uses that reduce cognitive burden on users". That way you can piggy-back (and make upstream improvements) to the general purpose tool, but provide more user-friendly APIs for specific goals. Similar to how Seaborn provides a more user-friendly API into Matplotlib for statistical visualization.

[vidartf]

How would this compare to e.g. nbviewer?

[choldgraf]

I think it performs a similar functionality to nbviewer in that it helps you go from notebook -> html quickly. The differences would be that nbviewer is a service while this would be something a person runs on their own computer, or a button you click to download a themed HTML bundle from your notebook.

[SylvainCorlay]

It may be ok to add an option to not execute the code in voilà and keep the existing output. This may be useful to enjoy the voilà template in a pure HTML mode.

Although what I think we should really be doing is try to have as much convergence and synergy between voilà, jupyter-book, nbconvert, thebelab and other projects.

[choldgraf]

Although what I think we should really be doing is try to have as much convergence and synergy between voilà, jupyter-book, nbconvert, thebelab and other projects

Agreed, that's why I opened this issue :-)

It sounds like maybe the thing to do is to keep the jupyter book template as a separate package, but find a way to distribute it such that it's installable to work with voila as well. If anyone can help step me through the setup.py incantation to make this work as expected, I'd appreciate it

[SylvainCorlay]

@choldgraf you may be interested in https://github.com/jupyter/nbconvert/pull/1056, in which @maartenbreddels refactors nbconvert's template system. It becomes a bit more similar to voilà.

[choldgraf]

Ah yes - I forgot about that one! I'll keep an eye on it.

For _only_ HTML generation in Voila, feel free to leave this issue open if it's something that is in-scope, but I'm also fine with folks closing it as out-of-scope

[vidartf]

The differences would be that nbviewer is a service while this would be something a person runs on their own computer, or a button you click to download a themed HTML bundle from your notebook.

I think many of us are hoping to end up with voilà as a service (either directly, or via another package). 😄

[benlindsay]

I really like the pattern of "nbconvert is fully-featured but very complex, and there are tools like voila, papermill, jupyter book etc that constrain those features for specific uses that reduce cognitive burden on users".

I 100% agree with this idea.

Yeah I agree with your intuition. I just notice that I keep having conversations with people where they ask "why can't I create a nice report from a notebook" and my response is "well you actually can, with nbconvert it's just XYZ flags and parameters".

I can't figure out the right nbconvert flags to i.e. remove all code cells, remove all stderr output, remove all In [*]: and Out [*]: and other similar beautification steps necessary to make a reasonably-nice looking HTML output, and I suspect most ordinary folks like myself can't either. (@choldgraf if you could point me to some resources for that I'd be much obliged)

It may be ok to add an option to not execute the code in voilà and keep the existing output. This may be useful to enjoy the voilà template in a pure HTML mode.

This would be cool, but even if that option wasn't added, I would find it super valuable if I could run something like voila mynotebook.ipynb --to-static output.html and have it still execute the notebook, and instead of serving a dynamic page, export to a static html using voila's template. Although if it could also enable something like voila mynotebook.ipynb --to-static output.html --no-execute that would be even more fantastic.

This looks like a really cool tool, so thanks for all the hard work on it!

[Juan-132]

This would be really cool to have +1

[vidartf]

It seems like what people want is a small Python script that runs nbconvert HMTL output with a set of sane options.

[benlindsay]

@vidartf yes, that would be a good first step, but it would be a lot easier to run viola mynotebook.ipynb --to-static output.html if that was available than it would be to figure out all the sane options myself

[fleimgruber]

It may be ok to add an option to not execute the code in voilà and keep the existing output. This may be useful to enjoy the voilà template in a pure HTML mode.

@SylvainCorlay Could you give a rough estimation on the effort and whether that would be feasible to have in a fork or a branch until the mentioned convergence and synergy are established?

Although what I think we should really be doing is try to have as much convergence and synergy between voilà, jupyter-book, nbconvert, thebelab and other projects.

[maartenbreddels]

Closing this as nbconvert is the tool to use for this (voila builds on top of, and upstream to it), e.g.:

$ nbconvert notebook.ipynb --execute --to html --template lab --HTMLExporter.theme=dark