Make formats more configurable, modular

[bollwyvl]

Use Case

from @bigzachattack on gitter

I am using nbconvert in a webapp with a re-factored full.tpl that is parameterized to extend basic.tpl or basic_no_input.tpl (which only shows output cells). It would be nice to offload the rendering work to a locally hosted nbviewer and just have the webapp for looking up the notebooks (until I can integrate with nbindex).

emphasis added after later conversation

Enabling this use case is a good way to allow people to use notebooks off-the-shelf in their application without some of the security headaches of running full kernels. :warning: nbviewer runs arbitrary javascript. :warning:

At present, formats are not configurable. Following the pattern for providers, the existing formatters html & slides should become nbviewer.formats.html and nbviewer.formats.slides, and it should be easy (or at least pythonic) to author new plugins, enable and configure them, and disable existing ones.

Proposal

Using entry_points, the workflow to add a new custom formatter such as above would be:

• implement a module mymodule

  • myformatter.py, a module that exposes some functions...
  • ... corresponding to the current dictionary-based approach: what arguments do they get? how dynamic can they really be?
    • nbconvert_template
    • label
    • icon
    • test, whether a notebook should present the formatter: can look at the whole notebook json/string
    • postprocess, do something with a nb, resources bundle, like rewrite/strip things
  • ... and some new ones, off the top of my head:
    • extra_template_paths, get nbconvert_template on the nbviewer template path
    • provider_url_frag, by default the entry_point key
    • extra_static_paths, in case you add branding... which is a whole other kettle of fish....
  • in setup.py

  entry_points={
    "nbviewer.formatter": "mykey = mymodule.myformatter"
  }

  • mymodule/templates/myformat.tpl a new template
  • mymodule/static/some-image-script-or.css maybe some new static stuff,
  • MANIFEST.in, for templates and static
• install mymodule with setup.py install/develop
  • or open source it, publish it on pip, and share with everyone :)
• run python -m nbviewer --with-mykey
  • optionally configure with environment variables
  • if #447 allows, also support --switch style configs, or #436, a traitleted config file

Blocked by #447.

[minrk]

I would guess the formatters should actually be registered with nbconvert, not nbviewer, right? I know we push back against setuptools, but if we want people to be able to register additional formatters, entry points are really the Python way to do it.

@takluyver, @ellisonbg, @fperez ?

[ellisonbg]

I was looking at ipymd recently (really cool) and thought the same exact thing...

On Wed, May 13, 2015 at 10:13 PM, Min RK notifications@github.com wrote:

I would guess the formatters should actually be registered with nbconvert, not nbviewer, right? I know we push back against setuptools, but if we want people to be able to register additional formatters, entry points are really the Python way to do it.

@takluyver https://github.com/takluyver, @ellisonbg https://github.com/ellisonbg, @fperez https://github.com/fperez ?

— Reply to this email directly or view it on GitHub https://github.com/jupyter/nbviewer/issues/457#issuecomment-101915382.

Brian E. Granger Cal Poly State University, San Luis Obispo @ellisonbg on Twitter and GitHub bgranger@calpoly.edu and ellisonbg@gmail.com

[takluyver]

I was also thinking nbconvert might want to make use of entry points. To that end, I'm working on a little package to discover entry points without using setuptools.

[ellisonbg]

:)

Sent from my iPhone

On May 14, 2015, at 10:18 AM, Thomas Kluyver notifications@github.com wrote:

I was also thinking nbconvert might want to make use of entry points. To that end, I'm working on a little package to discover entry points without using setuptools.

— Reply to this email directly or view it on GitHub.

[bollwyvl]

I agree nbconvert should be more easily extensible as well, but we'll always end up with some stuff specific to nbviewer, i think. URLs, icons, etc.

Ipymd is also great, in the way that yaml is great... As the best text editor experience for some structured data by a domain expert. In fact, i think some jekyll style front matter in --- --- would be an extremely good answer to "what is a cell"... It's once you want to add some meta data