Plotly plots are no longer displayed since plotly 6.1.0

[johannes-mueller]

Problem

For plotly versions >6.1.0 (probably by this PR plotly plots are no longer displayed in html files generated from jupyter notebooks with npsphinx. Using jupyter-nbconvert produces correctly working html files.

Debating on whether the culprit is nbsphinx or plotly I came to the conclusion that due to the fact that the error message is obviously produced by nbsphinx, probably there is a fix needed here.

What happens is, that plotly plots are rendered out byt a warning box

Data type cannot be displayed: application/vnd.plotly.v1+json

See a rendered example here

The error message is most probably from here

Googling the error message reveals that the problem is not uncommon and as it seems it mostly goes unnoticed.

Proposal

Two things should be considered

• Fix the issue itself and render the plots properly
• Turn the warning into an error. Most docs are built by a CI/CD and are not proofread in detail by a human at least not every time it newly builts. So there must be an option to make the docs built fail as soon as the above mentioned warning is issued.

[mgeier]

MRE please.

[mgeier]

jupyter/nbconvert#2235
plotly/plotly.py#5365

[johannes-mueller]

MRE

• Create an python environment, install plotly and nbsphinx
• Create a index.ipynb file with the content

from plotly.graph_objects import Scatter, Figure
Figure().add_trace(Scatter(x=[1,2,3], y=[2,3,4]))

• Create a conf.py file with the content extensions = ["nbsphinx"]
• Run python3 -m sphinx . build

The resulting build/index.html file shows the issue when plotly>=6.1.0 is installed. For plotly<6.1.0 it works.

Workaround

It seems to work if the environment variable PLOTLY_RENDERER=notebook is set. So adding

import os
os.environ["PLOTLY_RENDERER"] = "notebook"

seems to workaround it.

However, the resulting file gets quite big ~5 MB as the plotly code seems to be included into it.

[mgeier]

Thanks for the MRE and for the additional information!

I can reproduce the problem, but I think you have already found the solution. Is there anything to do in nbphinx?

The instructions for selecting the default Plotly renderer are there: https://plotly.com/python/renderers/#setting-the-default-renderer

I tried it with plotly<6.1.0, which seems to use 'plotly_mimetype+notebook' as a default, and the generated HTML file is 8.9 MB big.

With newer Plotly versions, they seem to have changed the default (or the heuristics for selecting the default).

The default now seems to be 'plotly_mimetype', which generated an HTML file of 5.5 kB, and which doesn't work, as you've described above.

When setting the 'notebook' renderer, the HTML file is 4.7 MB and it works again (as you already mentioned).

When setting the 'notebook_connected' renderer, the HTML file is 15 kB and it also works, but only with an internet connection.

You can choose whatever renderer you want, and if you want a different default, you'll have to ask the Plotly people.

If there is anything that we can improve on the side of nbsphinx, please let me know (or create a PR)!

[johannes-mueller]

An improvement for nbsphinx that I would suggest is to make the build fail instead of writing a warning into the html file. The problem is, that this issue goes unnoticed when the docs are created with a CI/CD. There needs to be some way for a CI/CD to catch it.

[mgeier]

In general, I tried to keep nbconvert's behavior as much as possible in nbsphinx unless there is a good reason to diverge. In this case, I did even go the extra step of showing the warning message, because IIRC nbconvert doesn't show anything and simply ignores the cell output (or at least did at the time).

Failing on any unknown MIME type might be a bit too disruptive, but maybe we could catch the special case of application/vnd.plotly.v1+json?

I'm also not sure if an error or a warning would be more appropriate.

Would you like to make a PR?

[johannes-mueller]

A warning would be ok. Then I could just use sphinx-build -W to make the docs build fail in the CI/CD. Then the team is also forced to take a bit more care with the docs.