Panel 1.4 has just been released! Checkout the release notes and support Panel by giving it a 🌟 on Github.

Embedding in Sphinx documentation#

One more option is to include live Panel examples in your Sphinx documentation using the nbsite.pyodide directive.

Setup#

In the near future we hope to make this a separate Sphinx extension, until then simply install latest nbsite with pip or conda:

pip install nbsite
conda install -c pyviz nbsite

add the extension to the Sphinx conf.py:

extensions += [
    ...,
    'nbsite.pyodide'
]

Configuration#

In the conf.py of your project you can configure the extension in a number of ways by defining an nbsite_pyodide_conf dictionary with the following options:

  • PYODIDE_URL: The URl to fetch Pyodide from

  • autodetect_deps (default=True): Whether to automatically detect dependencies in the executed code and install them.

  • enable_pwa (default=True): Whether to add a web manifest and service worker to configure the documentation as a progressive web app.

  • requirements (default=['panel']): Default requirements to include (by default this includes just panel.

  • scripts: Scripts to add to the website when a Pyodide cell is first executed.

  • setup_code (default=''): Python code to run when initializing the Pyodide runtime.

and then you can use the pyodide as an RST directive:

.. pyodide::

   import panel as pn

   slider = pn.widgets.FloatSlider(start=0, end=10, name='Amplitude')

   def callback(new):
       return f'Amplitude is: {new}'

   pn.Row(slider, pn.bind(callback, slider))

Examples#

The resulting output looks like this:

import panel as pn
slider = pn.widgets.FloatSlider(start=0, end=10, name='Amplitude')

def callback(new):
    return f'Amplitude is: {new}'

pn.Row(slider, pn.bind(callback, slider))

In addition to rendering Panel components it also renders regular Python types:

1+1
2
"A string"
A string

and also handles stdout and stderr streams:

import numpy as np
for i in range(10):
    print(f'Repeat {i}')
    for i in range(10000):
        np.random.rand(1000)
Repeat 0
Repeat 1
Repeat 2
Repeat 3
Repeat 4
Repeat 5
Repeat 6
Repeat 7
Repeat 8
Repeat 9
raise ValueError('Encountered an error')
Traceback (most recent call last):
  File "/Users/runner/work/panel/panel/panel/io/mime_render.py", line 185, in exec_with_return
    exec(compile(last_ast, "<ast>", "exec"), global_context)
  File "<ast>", line 1, in <module>
ValueError: Encountered an error

and supports _repr_<mime>_ methods that are commonly used by the IPython and Jupyter ecosystem:

class HTML:

    def __init__(self, html):
	    self.html = html

    def _repr_html_(self):
	    return self.html

HTML('<b>HTML!</b>')
HTML!

Usage#

The code cell will display a button to execute the cell, which will warn about downloading the Python runtime on first-click and ask you to confirm whether you want to proceed. It will then download Pyodide, all required packages and finally display the output.