Make it easy to use Panel with Sphinx-Gallery

[MarcSkovMadsen]

In https://discourse.holoviz.org/t/how-to-use-sphinx-gallery-with-panel/6035 pkrull asks for help using Panel with sphinx-gallery.

I think it could be quite powerful to support. It could even be used for the Panel or awesome-panel sites? It builds much faster than the notebooks in Panel !

All it takes to support sphinx-gallery is really a _repr_html_ method on Panel objects. For example something that returns an iframe.

Proof of concept

For example by adding the below to the sphinx conf.py file you will get it working

# Configure sphinx-gallery for panel

import panel as pn
from uuid import uuid4
from io import StringIO
from html import escape
import param

class PanelReprHTML(param.Parameterized):
    max_height=param.Integer(1000, bounds=(0,None))
    embed = param.Boolean(True)

    def __init__(self, object):
        self._object = object

    def _get_html(self):
        out = StringIO()
        self._object.save(out, embed=self.embed)
        out.seek(0)
        return escape(out.read())
    
    def _repr_html_(self):
        html = self._get_html()    
        uid = str(uuid4())       
        return f"""
<script>
function resizeIframe(){{
    setTimeout(() => {{
        var iframe = document.getElementById("{uid}");
        iframe.width = iframe.contentWindow.document.body.scrollWidth + 25;
        iframe.height = Math.min(iframe.contentWindow.document.body.scrollHeight + 10, {self.max_height});
        console.log(iframe.height)
    }}, "100");
    
}}
</script>        
<iframe id="{uid}" srcdoc='{html}' frameBorder='0' onload='resizeIframe(this)'></iframe>
"""

def _repr_html_(self):
    return PanelReprHTML(self)._repr_html_()

def add_repr_html():
    pn.viewable.Viewable._repr_html_=_repr_html_

PanelReprHTML.max_height=600
add_repr_html()

This is how it looks

Repository

A working repository is here https://github.com/MarcSkovMadsen/sphinx-gallery-panel-example

Todo

Some things that could be done to improve things

• Figure out how to make the resizeIframe more robust. With the Plotly example sometimes the iframe.contentWindow.document.body.scrollHeight is ~500px and sometimes ~1500px. That is why I've introduced the max_height parameter.
• Enable using either .save or panel convert to pyodide to generate the html
• Figure out how to use real screenshots of the Panel components in the gallery
• Add nicer css styling
• Reset panel before each example https://sphinx-gallery.github.io/stable/advanced.html#resetting-before-each-example
• Support multiple outputs

Question

How should we support it

• Documentation only
• Add the functionality to Panel and document it
• A separate python package. I could quickly make my own.
• Wait for sphinx-gallery support for _repr_mimebundle_. See ENH: Add support for capturing svg, png, and jpeg and _repr_mimebundle_ sphinx-gallery/sphinx-gallery#1138

[larsoner]

Just popping in to say that at the SG end I think sphinx-gallery/sphinx-gallery#1138 was close to being complete so @MarcSkovMadsen you could probably take it over and push it over the finish line if you want. I could fix the merge conflicts quickly if it would help.