Embed Panel Notebooks in Sphinx

The Sphinx-based Panel homepage includes an interactive Panel application:

which was embedded using

```{notebook} panel ../examples/homepage.ipynb

From what I could find, this uses the NotebookDirective functionality of the Holoviz nbsite.pyodide Extension.

However, this is not documented on the “Embedding in Sphinx documentation” page in the Panel Documentation. Also, the embedded notebook uses the row.embed() function, which makes the application run only on JavaScript.

Can I embed more complex Panel applications using the NotebookDirective? Is this currently missing from the “Embedding in Sphinx documentation” page?

The NotebookDirective has been in nbsite for a long time (+6 years!). This is used by many HoloViz projects to build their documentation from notebooks (in HoloViews for instance https://github.com/holoviz/holoviews/blob/main/doc/user_guide/Customizing_Plots.rst?plain=1).

The nbsite.pyodide extension is pretty new compared to that, it allows to run Python code in the browser leveraging Pyodide. Pydantic has recently added a similar functionality to their docs Welcome to Pydantic - Pydantic

We don’t recommend anyone using nbsite to build a website from notebooks (it’s on the README GitHub - holoviz-dev/nbsite: Build a tested, sphinx-based website from notebooks), instead we recommend using MySTNB or some alternative. We intend to extract the pyodide extension in its own project we would promote more, this just hasn’t happened yet due to lack of time :confused:

So if I understand correctly:

If I just want a single interactive Panel app embedded in my Sphinx documentation, I should use either the myst-nb or nbsphinx?

As far as I can tell, at least myst-nb only allows me to include entire notebook (as pages in the Sphinx documentation). It does not allow me to use a {notebook} directive to include a notebook in a markdown page.

Is that what nbsite would allow me to do?

As far as I can tell, at least myst-nb only allows me to include entire notebook (as pages in the Sphinx documentation).

I thought you could actually include some executed notebook but I’m not sure I tried that already. Check the end of this page Single page builds.

Yes nbsite would allow you to do that and you’re free to use it of course. Make sure you pin its version exactly, we regularly break it :upside_down_face: