How to embed Plotly graphs in Sphinx documentation and nbsphinx

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.

Same problem here. There exists https://github.com/plotly/plotlyhtmlexporter. Not sure how one could utilize it from nbsphinx. Also it messes up other HTML cells in my notebooks. — phantomas1234, Oct 25 '17 at 08:39
@phantomas1234 I've updated the question with a link to the GitHub issue I raised. Try the solution on there and see if it works for you. — bluprince13, Oct 25 '17 at 08:41
This is easier with the new `FigureWidget`. I can prepare an answer if there's interest. — astrojuanlu, Dec 27 '18 at 19:15

score 3 · Answer 1 · answered Jul 26 '19 at 09:21

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

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).
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

score 3 · Answer 2 · answered Aug 13 '19 at 20:44

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

Mikko Ohtamaa · Answer 3 · 2022-06-17T09:59:38.183

We had this issue for both sphinx_rtd_theme and furo theme. Because how Plotly and Sphinx themes using require.js, the default generated HTML output does not work within Sphinx context. You get various loading errors with require.js or other files.

Here is our solution:

Make sure your JavaScript loads at <head> in your theme. If it loads at the end of the <body> no workaround is going to work.
Server require.js locally from Sphinx _static folder
Configure require by using custom.js

Example conf.py:

html_js_files = [
    "require.min.js",  # Add to your _static
    "custom.js",
]

Example custom.js:

requirejs.config({
    paths: {
        base: '/static/base',
        plotly: 'https://cdn.plot.ly/plotly-2.12.1.min.js?noext',
    },
});

This way

Notebook correctly renders interactive diagrams when running in Jupyter
Notebook correctly renders interactive diagrams when viewed as static HTML files
Notebook correctly renders interactive diagrams when viewed on ReadTheDocs

See the example open-source documentation here and the example notebook.

score 1 · Answer 4 · answered Jul 01 '22 at 18:27

After trying many workarounds, the solution that worked for me was to add these lines at the beginning of the notebook.

import plotly
plotly.offline.init_notebook_mode()

None of the solutions involving modifying the options nbsphinx_prolog, nbsphinx_requirejs_options and html_js_files in the conf.py, work for me.

I'm ussing the sphinx_rtd_theme html theme and the following versions:

nbsphinx==0.8.9
sphinx-autobuild==2021.3.14
sphinx==4.4.0

score 0 · Answer 5 · answered Oct 06 '18 at 04:29

0

From Python, you can generate the HTML code to embed Plotly graphs with the plotly.tools.get_embed function.

import plotly.tools as tls

tls.get_embed('https://plot.ly/~chris/1638')

answered Oct 06 '18 at 04:29

erfanniks

1
2

Peque · Answer 6 · 2022-01-05T18:51:16.300

0

You can use the Jupyter Sphinx Extension:

.. jupyter-execute::

   import plotly.graph_objects as go

   trace = go.Scatter(
       x=[0, 1, 2, 3, 4],
       y=[0, 1, 4, 9, 16],
   )
   layout = go.Layout(title='Growth')
   figure = go.Figure(data=[trace], layout=layout)
   figure.show()

edited Jan 05 '22 at 18:51

answered Jul 22 '20 at 11:16

Peque

13,638
11
69
105

This doesn't seem to work with my pdflatex...is there some jupyter-execute setup you have earlier in the document? – Matt Ruge Sep 08 '20 at 16:04
@MattRuge I have not tried with LaTeX output, so I don't know. :-) – Peque Sep 08 '20 at 21:45
I made some progress by having the jupyter-execute dump the IMG bytes, shows up as a png in the latex pdf ``` .. jupyter-execute:: :hide-code: # Creates figure ## REDACTED FOR BREVITY img_bytes = fig.to_image(format="png") Image(img_bytes) ``` – Matt Ruge Sep 09 '20 at 15:38
I believe plotly won't generate a static plot by default unless you configure it explicitly with https://plotly.com/python/static-image-export/. I am currently looking to have a README.rst file with an interactive plotly graph in a Github repository, so far I have managed to with static image. – IF.Francisco.ME Jun 01 '21 at 00:39

score 0 · Answer 7 · edited Sep 09 '21 at 03:13

0

When Sphinx generate the document it doesn't describe the plotly library, so add the following line into your HTML page:

<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>

then the page will be alive again.

edited Sep 09 '21 at 03:13

bad_coder

11,289
20
44
72

answered Sep 08 '21 at 23:57

Gabriel Lima

11
2

score -1 · Answer 8 · answered Aug 30 '22 at 18:28

Try this at the top of your notebook:

import plotly.io as pio
pio.renderers.default = "sphinx_gallery"

This renderer makes sure your notebook (or cell output, or something, not sure!) includes the javascript resources that your cell output needs to render the plot.

Other renderers, or settings, might achieve this as well. But so far this is the only renderer I've tried where I can build notebooks with sphinx (jupyter book, actually), and the interactive plots show up in the build.

How to embed Plotly graphs in Sphinx documentation and nbsphinx

8 Answers8