Plotly plots show locally but not on RTD

[astrojuanlu]

Details

• Read the Docs project URL: https://readthedocs.org/projects/juanlu-poliastro/
• Build URL (if applicable): https://readthedocs.org/projects/juanlu-poliastro/builds/7484265/
• Read the Docs username (if applicable): Juanlu001

Expected Result

I expected the Plotly plots to show in RTD the same way as locally.

Actual Result

Because of readthedocs/sphinx_rtd_theme#328, I am using a hack, which is adding require.js at the top of the page from a notebook cell:

from IPython.display import HTML
HTML('<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"></script>')

https://juanlu-poliastro.readthedocs.io/en/latest/examples/Visualizing%20the%20SpaceX%20Tesla%20Roadster%20trip%20to%20Mars.html

I tried to build locally and the result is correctly seen in Firefox and Chrome.

When deploying to RTD, on Firefox this gives several JavaScript ReferenceErrors but the plot loads. These errors come from RTD scripts:

ReferenceError: _ is not defined  # doctools.js:15
ReferenceError: $ is not defined  # readthedocs-doc-embed.js:1
ReferenceError: jQuery is not defined  # Visualizing the SpaceX Tesla Roadster trip to Mars.html:681

In Chrome, on the other hand, I get similar errors but the plot never loads.

When I try to add jQuery as suggested in plotly/plotly.py#1033 (comment):

HTML('''
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
''')

https://juanlu-poliastro.readthedocs.io/en/latest/examples/Plotting%20in%203D.html

Then I get errors coming from require.js and the plot doesn't load in Firefox nor Chrome.

[humitos]

juanlu-poliastro.readthedocs.io/en/latest/examples/Plotting%20in%203D.html

Then I get errors coming from require.js and the plot doesn't load in Firefox nor Chrome.

I do see the plots in Firefox 61.0.1 (64-bits) on Linux Arch even with the errors that are shown in the Firefox console. On the other hand in Chrome it works, does not work, crashes my Chrome and behaves in a crazy way 😁

We will need to research more about this, but I can tell that after refreshing a couple of times the page from Chrome Versión 61.0.3163.79 (Build oficial) (64 bits) (with and without cache) I was able to see the graph:

I'd say that there is something that depends on the order of loading those js libraries...

I'm not sure how to continue debugging this, though.

[astrojuanlu]

Thanks for your prompt response @humitos! If there's anything I can do to help from my side, please let me know.

[astrojuanlu]

I created a repo with a much simpler test case to display the buggy behavior:

https://github.com/Juanlu001/rtd-js-test

Result:

https://rtd-js-test.readthedocs.io/

There are two branches (one with the RTD theme and one with Alabaster) and five notebooks that display four different combinations + an interactive widget.

• With the Alabaster theme, all the five notebooks are shown and no relevant JavaScript errors appear in the developer console, both locally and at https://rtd-js-test.readthedocs.io/en/alabaster/.
• With the RTD theme, there are several different behaviors:
  • The notebooks that do not add require.js at the top (as suggested in Blank plot in html using nbconvert (basic template) plotly/plotly.py#1033 (comment)) raise Uncaught ReferenceError: requirejs is not defined and Uncaught ReferenceError: require is not defined errors and do not show anything, neither locally nor online.
  • The notebooks that add require.js at the top show very long errors and intermittently show the plot online (in Firefox or Chrome) or almost always locally.
  • The notebook that uses a widget works everywhere.

I still did not have time to test what @Blendify started in readthedocs/sphinx_rtd_theme#545, but the fact that Alabaster does not show display this behavior would indicate that there it's a RTD + RTD theme specific behavior.

@jonmmease suggested in plotly/plotly.py#1033 that the problem might be require.js rather than jQuery.

Also, although this was first reported in spatialaudio/nbsphinx#128, I doubt that this can be fixed on the nbsphinx side (cc @mgeier, @bluprince13).

My current workarounds are:

• Use widgets, because they seem to work better.
• Use an unreleased version of rtd_sphinx_theme that should work.
• Use a totally different theme.

I acknowledge that we have to conceal expectations and settle on who should handle this, so can we try to reach an agreement?

[astrojuanlu]

By the way, one of the JS errors I'm getting contains the string "/Users/anthony/dev/readthedocs.org/bower_components/jquery/jquery.js". Is this normal?

[davidfischer]

By the way, one of the JS errors I'm getting contains the string "/Users/anthony/dev/readthedocs.org/bower_components/jquery/jquery.js". Is this normal?

Can you tell me where you see this error? I don't see it on
https://rtd-js-test.readthedocs.io/
or
https://rtd-js-test.readthedocs.io/en/alabaster/

[davidfischer]

As to fixing the underlying issue, that will be done here:
readthedocs/sphinx_rtd_theme#545

Until then, try the workaround documented here:
readthedocs/sphinx_rtd_theme#328 (comment)

In general, you get better performance by loading JS at the end of the page rather than in the head as loading JS blocks rendering until it is fetched. However, no other Sphinx theme seems to care about that performance so I guess the RTD theme won't either.

[astrojuanlu]

I see that error here: https://rtd-js-test.readthedocs.io/en/latest/Connected%20-%20require.js%20Hack.html

Glad to know readthedocs/sphinx_rtd_theme#545 is still under consideration, I was worried because the branch is lagging a bit behind :) The problem with the workaround is that it's not that easy to modify the output of nbsphinx, as it's not a .rst file where you insert the contents of the notebook. Right @mgeier?