Search does not work for docs built with 1.8.0

[dkliban]

Subject: Docs built with sphinx 1.8.0 have broken search

Problem

• Search returns no results for all queries. When I build using 1.7.9 everything works fine.

Procedure to reproduce the problem

• build docs with sphinx 1.8.0
• try to search the docs using the search textbox
• no results ever show

Expected results

Search works

Environment info

• OS: Fedora 28
• Python version: 3.6
• Sphinx version: 1.8.0

[tk0miya]

Sorry, I can't reproduce the error. Could you share your project or reproducible example please?

[dkliban]

I am able to reproduce using: https://github.com/dkliban/pulp/tree/broken-sphinx

However, I just realized that this only occurs when using the 'sphinx-rtd-theme'. After I uninstalled 'sphinx-rtd-theme' the problem goes away. Should I file the bug with https://github.com/rtfd/sphinx_rtd_theme ?

[ImportanceOfBeingErnest]

To see this bug in action, see the matplotlib search (as long as this isn't reverted to use sphinx 1.7.9).

The error seems to be

Uncaught ReferenceError: Stemmer is not defined
    at Object.query (searchtools.js:9)
    at Object.setIndex (searchtools.js:3)
    at <anonymous>:1:8
    at p (jquery.js:1)
    at Function.globalEval (jquery.js:1)
    at text script (jquery.js:1)
    at Qb (jquery.js:1)
    at A (jquery.js:1)
    at XMLHttpRequest.<anonymous> (jquery.js:1)

As far as I can tell matplotlib does not use the 'sphinx-rtd-theme'; but of course some other customization that is done may be responsible, maybe an old jquery in use?

[tk0miya]

@dkliban Thank you for comment. I reproduced this.
And I just post readthedocs/sphinx_rtd_theme#672 to fix this from sphinx_rtd_theme side.

Note: This was added in #5207. It updated documentation_options.js which was added in 1.7. But sphinx_rtd_theme has not refered it.

[ImportanceOfBeingErnest]

It seems sphinx 1.8.1 is out without this being fixed. Could someone comment on the solution here?

It looks like the searchtools.js needs some variables from another javascript and currently the user is resposible for including that other javascript? Is this documented somewhere?

[tk0miya]

The variables are defined in documentation_options.js. But sphinx_rtd_theme does not load it.
Unfortunately, the theme has loaded JavaScript files via their custom solution. So the changes on Sphinx does not effect to the theme.

Until merging readthedocs/sphinx_rtd_theme#672 , you need to pin Sphinx==1.7.9 or customize the theme manually.

[mitya57]

sphinx_rtd_theme and matplotlib are not the only themes that got broken with this. Another example is scipy/scipy-sphinx-theme#9, and I think there will be other examples of breakage.

Maybe it's possible to add a fallback for such themes, like we did in past (e.g. #4107)?

[tk0miya]

@TimKam do you have any idea for @mitya57 's comment?

[TimKam]

I will take a look. Should be possible for me to add such a fallback, if this is okay with you.

[mitya57]

There is a new pull request in #5590. Any testing is appreciated. Please consider assigning it to 1.8.2 milestone.

[tk0miya]

Fixed by #5590. Thank you @mitya57 !