Plotly graphs not showing in documentation

[bluprince13]

Graphs generated using plotly are not showing in the documentation. Matplotlib plots show up just fine.

[mgeier]

Thanks for the report! Can you please provide an example notebook that shows the issue?

[bluprince13]

https://gist.github.com/bluprince13/1a53aabe99b5a4a1ec2007a90889115b

The plots don't render on Github either.

[mgeier]

OK, thanks for the example.

Just for the record, it seems to work on nbviewer: http://nbviewer.jupyter.org/gist/bluprince13/1a53aabe99b5a4a1ec2007a90889115b

Does it work with nbconvert?

I don't know how this is supposed to work.
Your example has two output cells. The first one has two alternative contents of the type text/vnd.plotly.v1+html and text/html, respectively. The second output cell also has two alternative contents with the same two types.
nbsphinx includes the text/html part in both cases, because it doesn't know the other type.

When loading the Sphinx-generated HTML page, I get those errors in the JS Console:

ReferenceError: define is not defined
ReferenceError: require is not defined

[bluprince13]

I asked a question on stackoverflow on this as well. No responses yet.

[bluprince13]

I can confirm that this does work with nbconvert 5.3.1. So, why is the Sphinx generated documentation not showing it ...

[mgeier]

Thanks for checking it out with nbconvert.
Since it is working there, I only had to check what they are doing and I found the problem: require.js is not available!

Since nobody has missed it before, I don't think it's worth including it by default in nbsphinx.

For now, you can use this in your conf.py:

def setup(app):
    app.add_javascript('https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js')

... but probably there is a better solution?
Any ideas?

[bluprince13]

Hmmm...did you check if it solves the problem? It didn't work for me, but I am not sure if there was some other factor at play.

In terms of a solution, is it feasible to get nbsphinx to generate a meaningful warning if there are missing scripts?

[mgeier]

Yes, I checked.

No, I don't think that's possible.

[astrojuanlu]

I have tried this workaround, but still I get the ReferenceError: requirejs is not defined.

Code: poliastro/poliastro@master...Juanlu001:master
Build: https://readthedocs.org/projects/juanlu-poliastro/builds/6272017/
Result: http://juanlu-poliastro.readthedocs.io/en/latest/examples/Plotting%20in%203D.html (edit: this might be unavailable for future readers)

I suspect this is because the scripts are loaded at the bottom of the page, after require.js is requested by the plotly graphs.

[astrojuanlu]

I see you're tracking this here readthedocs/sphinx_rtd_theme#328

[mgeier]

Did you try it with a different HTML theme?

[astrojuanlu]

I can confirm locally that using a different theme fixes the problem, so this is not a nbsphinx issue.

[mgeier]

@Juanlu001 OK, thanks! Did you try if readthedocs/sphinx_rtd_theme#467 fixes the problem?

[astrojuanlu]

Yes it does! 😁 see readthedocs/sphinx_rtd_theme#467 (comment)

[astrojuanlu]

readthedocs/sphinx_rtd_theme#467 was closed because it was too complex, but now the issue is being tackled at readthedocs/sphinx_rtd_theme#545.

[astrojuanlu]

Some more info in readthedocs/readthedocs.org#4367 (comment)

[mgeier]

readthedocs/sphinx_rtd_theme#545 has finally been merged into the master branch, now we only have to wait for a new release ...

[manycoding]

@mgeier I would opt for adding require.js to nbsphinx by default.
I have been tackling this issue (which now seems obvious) for some time, mostly because there are a lot of things involved and you don't know where is the problem - jupyter, plotly, sphinx, nbsphinx, rtd, or your code :)

[mgeier]

@manycoding I guess if nbconvert and nbviewer include require.js, it makes sense to have it in nbsphinx, too.

Would you like to make a PR?

[miohtama]

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