Embed plotly graph in a Sphinx doc

Question

I tried using nbsphinx to embed a Jupyter notebook containing plotly plots, but the plots don't show up in the documentation, even though they look fine on the Jupyter notebook.

How can I embed a plotly graph in Sphinx documentation? I could include them as images, but is there a better way? It'd be nice to have the interactivity!

What I want to do is replicate this page. It has Jupyter notebook style in and out blocks, and it shows interactive plots made using plotly. How can I do that?

GitHub issue raised here.

Answer 1

I can see two solutions to embed your notebook cells with plotly figures in a sphinx documentation.

1. Convert the notebook to html using nbconvert or nbsphinx. Be sure to use the notebook renderer in order to include the plotly javascript bundle (maybe this was the reason why your figures did not display): see https://plot.ly/python/renderers/ for the documentation on plotly renderers. Then you can include the html in your sphinx doc with various solutions (see Include standalone HTML page in sphinx document).
2. Use sphinx-gallery (https://sphinx-gallery.github.io/) with its plotly scraper. With sphinx-gallery you write your doc page as a python script which is converted to rest by the sphinx-gallery extension of sphinx. In order to configure the scraper see https://sphinx-gallery.github.io/advanced.html#integrate-custom-scrapers-with-sphinx-gallery. We have also a minimal repository showing how to use plotly and sphinx-gallery together in https://github.com/plotly/plotly-sphinx-gallery. https://github.com/plotly/plotly-sphinx-gallery

Answer 2

The graph itself is an HTML inside jupyter notebook file. You can open notebook.ipnb file in any text editor, find where HTML of the graph starts, copy all this html into html file ans save it , say a.html, and then just insert raw html in RST doc.

.. raw:: 
    :file: a.html