Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How to include the JavaScript for widgets? #84

Closed
mgeier opened this issue Dec 15, 2016 · 6 comments · Fixed by #345
Closed

How to include the JavaScript for widgets? #84

mgeier opened this issue Dec 15, 2016 · 6 comments · Fixed by #345
Labels

Comments

@mgeier
Copy link
Member

mgeier commented Dec 15, 2016

Is it really necessary to load jupyter_sphinx.embed_widgets?

Since #76, only adding the JS file is necessary, nothing else from jupyter_sphinx.embed_widgets is needed, right?

What about adding a config option like nbsphinx_widgets?
This could be False by default and True if widgets should be displayed.
It could even be set to an alternative path to the JS file (e.g. for offline use).

See also jupyter/jupyter-sphinx#3.

@mgeier
Copy link
Member Author

mgeier commented Nov 26, 2018

It looks like nbconvert still doesn't save the widget state when executing the notebook, but people are working on it, see jupyter/nbconvert#900.

In the meantime, the notebook state has to be saved manually with the menu item "Save Notebook Widget State". See also https://ipywidgets.readthedocs.io/en/stable/embedding.html#using-the-nbsphinx-project.

The necessary JavaScript can be added like this in conf.py:

For Sphinx >= 1.8:

from ipywidgets.embed import DEFAULT_EMBED_REQUIREJS_URL

html_js_files = [
    'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js',
    DEFAULT_EMBED_REQUIREJS_URL,
]

A work-around for Sphinx < 1.8 is this:

from ipywidgets.embed import DEFAULT_EMBED_REQUIREJS_URL

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

Note that ipywidgets 7.4 is required.

@mgeier
Copy link
Member Author

mgeier commented Sep 22, 2019

A little update 1: Saving the widget state now works in nbconvert

A little update 2: Since #302, require.js is included by default (see also #327).

Therefore, only the ipywidgets URL should be necessary:

from ipywidgets.embed import DEFAULT_EMBED_REQUIREJS_URL

html_js_files = [
    DEFAULT_EMBED_REQUIREJS_URL,
]

The jupyter_sphinx module is not needed anymore (but you can of course still use it, if your prefer).

@dgasmith
Copy link

This isn't working for me. Double checking that nbsphinx/nbconvert are up to date and the state is correctly embedded in the html doesn't show any obvious troubles. JS errors on the page are:

Uncaught ReferenceError: define is not defined
    at embed-amd.js:1
theme.js:222 Uncaught ReferenceError: module is not defined
    at theme.js:222
jquery.js:2 jQuery.Deferred exception: SphinxRtdTheme is not defined ReferenceError: SphinxRtdTheme is not defined
    at HTMLDocument.<anonymous> (file:///Users/daniel/Gits/QCArchiveExamples/build/html/basic_examples/molecule.html:497:11)
    at e (file:///Users/daniel/Gits/QCArchiveExamples/build/html/_static/jquery.js:2:29453)
    at t (file:///Users/daniel/Gits/QCArchiveExamples/build/html/_static/jquery.js:2:29755) undefined
k.Deferred.exceptionHook @ jquery.js:2
jquery.js:2 Uncaught ReferenceError: SphinxRtdTheme is not defined
    at HTMLDocument.<anonymous> (molecule.html:497)
    at e (jquery.js:2)
    at t (jquery.js:2)

But these seems fairly common with Sphinx/RTD. Any ideas of what to try here?

@mgeier
Copy link
Member Author

mgeier commented Oct 24, 2019

@dgasmith Yes, sorry, this is indeed broken (which I didn't know when writing my comment above).

This has been fixed in #334, but there hasn't been a new release yet.

Maybe I will even implement loading the widget JS by default, see jupyter-widgets/ipywidgets#2284 (comment)

I'd be happy to hear feedback about that!

@dgasmith
Copy link

@mgeier Awesome, I just checked with current master and everything works great! Reading through your PR I understood that the require.js extra wasn't required, but it appears to still be needed in the projects conf.py. My familiarity with Sphinx is limited so I might be misunderstanding there.

Any ideas on a timeline for the next release? If not I can pull the GitHub tags.

@mgeier
Copy link
Member Author

mgeier commented Oct 31, 2019

@dgasmith Thanks for checking!

Reading through your PR I understood that the require.js extra wasn't required, but it appears to still be needed in the projects conf.py.

nbsphinx_requirejs_path has a default value, so it should not be necessary to specify it explicitly (unless you want to use a different path/URL).

But, as I said, there is still an issue with require.js being loaded after the widgets URL, which is fixed in the master branch.

Any ideas on a timeline for the next release? If not I can pull the GitHub tags.

I want to check first if I can make embedding the widget JS fully automatic before the next release.

If you are in a hurry, you should just depend on the master branch (but using a specific release to avoid breakage along the way).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants