How do I get Juypter Widgets to render properly through Sphinx and nbconvert?

Question

I am using Jupyter widgets in my notebooks. My notebooks are then processed through Sphinx + nbsphinx to generate HTML. I noticed that even the simple example below shows a slider in my notebook (on Jupyter Lab), but the generated, corresponding HTML page does not show the slider.

import ipywidgets as widgets

widgets.IntSlider()

I know there is a way to get the widget to render from observing the published HTML of Juypter Widgets. Their book is built using Sphinx + nbsphinx. When I look at their Sphinx configuration, they have the following extensions enabled.

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.intersphinx',
    'sphinx.ext.mathjax',
    'nbsphinx',
    'jupyter_sphinx.execute',
    'IPython.sphinxext.ipython_console_highlighting',
]

I believe the key to rendering widgets from a notebook to the published HTML is the jupyter_sphinx.execute extension. My project's extensions are as follows. Note that when issuing make html there is a warning to change jupyter_sphinx.execute to jupyter_sphinx (it does not matter, however, as using either still does not render the widgets).

extensions = [
    'sphinxcontrib.bibtex',
    'nbsphinx',
    'sphinx.ext.mathjax',
    'sphinx_sitemap',
    'jupyter_sphinx'
]

Issuing the command pip list I see the following packages.

jupyter-client                     6.1.3
jupyter-console                    6.1.0
jupyter-core                       4.6.3
jupyter-server-proxy               1.5.0
jupyter-sphinx                     0.3.2
jupyterlab                         2.1.4
jupyterlab-commenting-service      0.2
jupyterlab-server                  1.1.5
nbconvert                          6.0.7
nbsphinx                           0.8.0
sphinx-autobuild                   2020.9.1
sphinx-rtd-theme                   0.5.0
sphinx-sitemap                     2.2.0
sphinxcontrib-applehelp            1.0.2
sphinxcontrib-bibtex               1.0.0
sphinxcontrib-blockdiag            2.0.0
sphinxcontrib-devhelp              1.0.2
sphinxcontrib-htmlhelp             1.0.3
sphinxcontrib-jsmath               1.0.1
sphinxcontrib-qthelp               1.0.3
sphinxcontrib-serializinghtml      1.1.4
sphinxcontrib-websupport           1.2.2

If you look at their ipynb source code, all you see is widgets.IntSlider() in one of the cells (there's nothing special happening). According to nbconvert, live rendering of widgets has been available since version 4.3.

Any ideas on what additional configuration or steps I am missing?

Answer 1

Ok, the solution was easier than I thought. In Jupyter Lab, go to Settings > Save Widget State Automatically and make sure that option is checked.

Alternatively, you can go to ~/.jupyter/lab/user-settings/@jupyter-widgets/jupyterlab-manager/plugin.jupyterlab-settings and configure the settings as follows.

{
    // Jupyter Widgets
    // @jupyter-widgets/jupyterlab-manager:plugin
    // Jupyter widgets settings.
    // ******************************************

    // Save Jupyter widget state in notebooks
    // Automatically save Jupyter widget state when a notebook is saved.
    "saveState": true
}

The solution was not so clear, but this page gave me some hints.