Add top-level save and render utilities

[philippjfr]

This PR adds top-level hv.save and hv.render utilities which we have long wanted and are much more obvious than the obscure hv.renderer(backend).save(obj, filename, fmt) and hv.renderer(backend).get_plot(obj).state APIs.

• hv.render: Renders the holoviews object to the representation in of the backend, e.g. for bokeh returns bokeh Figure objects. This is very useful for incorporating HoloViews into a workflow where you're working directly with the underlying library but want to take advantage of some plot type that's only provided by HoloViews.

• hv.save: Convenient API for saving holoviews objects to any format, including png, svg, gif, mp4, and both scrubber and selection widgets.

Here is a notebook demonstrating what the API looks like in practice (note that because of the way exported HTML files are embedded some of the widget examples do not work but will work when working with the exported file directly).

• Add documentation

[philippjfr]

If anyone has suggestions on where to document these that would be very helpful.

[jbednar]

Looks really useful! I have wanted something like this for a long time, but never took the time to write it, so I am very glad you did.

[jbednar]

will need to be specified?

[jbednar]

That last bit is confusing to me -- what fmt other than 'html' would be more explicit? If you mean widgets vs. scrubber, please say that explicitly -- i.e. that .html will by default be XX, but if you don't want that, specify YY.

[philippjfr]

Sounds good.

[jbednar]

Renders the HoloViews object to the corresponding object in the specified backend, e.g. a Matplotlib or Bokeh figure.

The backend defaults to the currently declared default backend. The resulting object can then be used with other objects in the specified backend. For instance, if you want to make a multi-part Bokeh figure using a plot type only available in HoloViews, you can use this function to return a Bokeh figure that you can use like any hand-constructed Bokeh figure in a Bokeh layout.

[philippjfr]

Sounds good.

[philippjfr]

Just noticed all the +1's on this issue: #1819 Adding this is really overdue. I'll try to add this to the getting started and user guides in the appropriate places.

[jlstevens]

And if the format isn't supported?

[philippjfr]

Renderer.save automatically adds the file extension no matter what file extension you supply (which I've found pretty annoying tbh). So if you don't supply a file extension it'll pick whatever the default is.

[jlstevens]

I am happy with these utilities and I do think they are useful. I'm not entirely sure where in the docs this should go though I think save can be mentioned early on in our current exporting and archiving user guide.

Maybe render can be the first thing in 'Working with Plots and Renderers' though it would be nice to mention it earlier. Maybe at the first point where we show multiple backend support?

Happy to merge the code now for a subsequent docs PR or wait for that material to be added here.

[jbednar]

Wherever render is mentioned, please also mention finalize_hooks, because I think many of the things people think they need render for can be done more cleanly using finalize_hooks, allowing them to spend more of their time in the HV world instead of leaving it to start working with Bokeh directly (except where strictly necessary, using finalize_hooks).

[philippjfr]

I know we've already gone through the whole finalize_hooks vs. final_hooks mess, but how do you feel about renaming finalize_hooks to just hooks (with a proper deprecation cycle of course)? Initially we had considered adding initial_hooks but there is effectively no use for them and the current name is quite annoying to type out.

[philippjfr]

I am happy with these utilities and I do think they are useful. I'm not entirely sure where in the docs this should go though I think save can be mentioned early on in our current exporting and archiving user guide.

I think this is probably way to deep into the material, I'd like at least a mention in getting started section and I'll also add FAQ items.

[philippjfr]

I've overhauled the FAQ a bit with sections for save and render/finalize_hooks (also applied some unrelated edits). Will look at the getting started and user guides next.

[philippjfr]

@jlstevens @jbednar Ready for another round of review, here's what I've done for documentation:

• FAQ items about hv.save and hv.render separately
• Very short entry about hv.save in Getting Started Introduction
• Mentioned hv.save as alternative to %%output filename=... in Exporting user guide
• Detailed description of hv.render and finalize_hooks in Plots and Renderers.

[philippjfr]

I've now also aliased finalize_hooks to hooks and marked this PR with deprecated to make sure that when we write up the release notes the deprecation of finalize_hooks is mentioned.

[jbednar]

Looks great, thanks! My wording suggestions are minor, and if any of them are not accurate, please disregard them but try to clarify it in the correct direction instead.

[philippjfr]

Review comments now addressed, ready to merge.

[philippjfr]

@jlstevens Please review and merge this.

[jlstevens]

Looks good. Merging.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.