Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Fix searchindex.js loading when ajax fails (because e.g. CORS in embedded iframes) #15649
Searching the documentation does not work in Jupyterlab's Matplotlib reference pane, because
This PR partially fixes the issue by restoring the backup-method of using a
The search page now returns a list of relevant links. The preview snippets that load underneath each link still do not work because of the same CORS issue (and cannot be loaded in an alternate way).
Context of the fix:
If the XHR fails,
Additionally, Sphinx has changed the way
What about the original issue, that XHR fails?
The original AJAX/XHR request fails because the CORS (Cross-Origin-Resource-Sharing) preflight OPTIONS request returns a 405 Method Not Allowed response from matplotlib.org. Even though a subsequent GET would return the correct
This issue has to be fixed in the web server configuration. For the OPTIONS request it should instead respond with a 200 OK and the headers
What about the older docs?
I am not sure how to go about potentially getting this fix back-ported to older versions of Matplotlib documentation (Is that a thing? Or are those frozen?). The Jupyterlab reference pane only points to the latest version on matplotlib.org, so it is not an immediate concern. It's probably better to just have the CORS issue on the server fixed.
Matplotlib's website is built upon a vendored version of the sphinx_rtd_theme, which was forked years ago. This fact already led to some problems with search in the past, see #12216.
I wouldn't worry about older versions.
A more future-proof version would probably be to follow sphinx-doc/sphinx@55c5168 and replace the whole:
That way, loading searchindex.js will no longer be dependent on AJAX or searchtools.js (which is, even in sphinx_rtd_theme, inherited from the sphinx basic theme template), which may in future versions of sphinx again remove the
Hopefully a more future-proof fix, removing the dependency on ajax and searchtools.js altogether. (After loading, searchindex.js itself does depend on searchtools.js, but both are updated with the version of sphinx that is used, unlike this template.) Because the script is loaded with `defer` and also right at the end of the body, the size of searchindex.js should not block loading the rest of the page (one of the arguments for using ajax).
Referenced the correct pull request this time.
This solution removes the need for searchtools.js or ajax for loading searchindex.js altogether (after loading, searchindex.js itself does depend on searchtools.js, but both are updated with the version of sphinx that is used, unlike this template).
From the author: sphinx-doc/sphinx#3620 (comment), the argument for using ajax to load searchindex.js seems to have been that it is a large file (~1.5 MB currently) and might block loading the page. But since the template block had already been moved to the very bottom of the page, just before
Also in the pull request sphinx-doc/sphinx#6091 the conclusion seems to be that it works fine on all browsers.
Did a bit more digging and found that this issue became visible mainly as the result of Jupyterlab iframe containing a
This same issue also affects documentation for Numpy, Scipy, Pandas, Sympy, IPython and even the main Python.org docs. None of them however return no results, which is why this fix should still be merged in Matplotlib. It also allows loading search results when opened as a local
A note about our website hosting: It is primarily hosted through githubpages and proxied through cloudflare. It looks like CF passes through CORS headers (https://support.cloudflare.com/hc/en-us/articles/200308847-Using-cross-origin-resource-sharing-CORS-with-Cloudflare ) so to fix this on the server side we would have to figure out how to configure github pages.
https://26552-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/search.html?q=plot <- link to built docs, verified it works.
Thanks for merging!
I also monkey-patched the built https://26552-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/search.html into the offending Jupyterlab iframe
I guess the server configuration can wait. The SymPy, Pandas, IPython and Python.org docs all have the same problem. jupyterlab#7506 should also mostly mitigate it.