Search broken on ReadTheDocs

[dallan-keylogic]

When I try to search the IDAES documentation, no results are returned without even a message telling me that no results were found. Both Chrome and Edge had the same issue. In the browser's DevTool console, the following errors are returned:

doctools.js:15 Uncaught TypeError: Cannot read properties of undefined (reading 'noConflict')
    at doctools.js:15:8
jquery.js:2 jQuery.Deferred exception: _ is not a function TypeError: _ is not a function
    at Object.performSearch (https://idaes-pse.readthedocs.io/en/stable/_static/searchtools.js:121:29)
    at Object.init (https://idaes-pse.readthedocs.io/en/stable/_static/searchtools.js:64:16)
    at HTMLDocument.<anonymous> (https://idaes-pse.readthedocs.io/_/static/javascript/readthedocs-doc-embed.js:1:25956)
    at j (https://idaes-pse.readthedocs.io/en/stable/_static/jquery.js:2:29999)
    at k (https://idaes-pse.readthedocs.io/en/stable/_static/jquery.js:2:30313) undefined
r.Deferred.exceptionHook @ jquery.js:2
jquery.js:2 Uncaught TypeError: _ is not a function
    at Object.performSearch (searchtools.js:121:29)
    at Object.init (searchtools.js:64:16)
    at HTMLDocument.<anonymous> (readthedocs-doc-embed.js:1:25956)
    at j (jquery.js:2:29999)
    at k (jquery.js:2:30313)

[adowling2]

OS and browser versions?

[dallan-keylogic]

Windows 11, Microsoft Edge Version 103.0.1264.49 (Official build) (64-bit). Google Chrome Version 103.0.5060.114 (Official Build) (64-bit)

[lbianchi-lbl]

I can confirm this occurs on my system, too:

• Ubuntu 20.04, Firefox 99

[ksbeattie]

does this happen when the docs are built locally?

[ksbeattie]

does this happen when the docs are built locally?

Answering my own question: yes it does. On my macos laptop, firefox.

[lbianchi-lbl]

@ksbeattie OK, after some rabbit-hole spelunking and A/B comparison with the Pyomo docs (where the search is working), I've realized that in IDAES we have a lot more files in the docs/static directory, including several JS files, while Pyomo only has one (https://github.com/Pyomo/pyomo/tree/main/doc/OnlineDocs/_static). My working theory is:

• If a certain file is present in the static directory, it will be used instead of the one provided by Sphinx (or, more likely, the Sphinx theme)
• Looking at the commit history, it seems that most of the files in static were added with the first docs commit (possibly by mistake, possibly because it was needed or easier at the time?)
• This might mean that we've effectively "frozen" the JS files to that version, preventing e.g. fixes applied upstream in Sphinx/sphinx-rtd-theme to take effect

If that's the case, we should be able to:

1. Try deleting the JS files (which should cause the up-to-date files from Sphinx/sphinx-rtd-theme to be copied to the _build directory (when running locally) and/or the served directory (on RTD)
2. See if the search works again

[lbianchi-lbl]

Following up on that: this is the diff between the search result HTML for IDAES and Pyomo for the same query "model": https://www.diffchecker.com/WPe16Zn0

Apart from the expected differences, I see that:

• For Pyomo the src for some of the assets is https://assets.readthedocs.org/static/ (i.e. a common, project-independent source), whereas for IDAES it's https://idaes-pse.readthedocs.io/_/static/ (i.e. the same directory where the rest of the project-specifc Sphinx build files are located)

[lbianchi-lbl]

OK, it looks like removing the JS files worked: compare

• https://idaes-pse--932.org.readthedocs.build/en/932/search.html?q=model&check_keywords=yes&area=default

  

• https://idaes-pse.readthedocs.org/en/stable/search.html?q=model&check_keywords=yes&area=default (is empty)

  

[dallan-keylogic]

Did this fix ever get deployed? Trying to search ReadTheDocs this morning with Edge, I'm still getting no results when searching, with the following errors in the dev console:

doctools.js:15 Uncaught TypeError: Cannot read properties of undefined (reading 'noConflict') at doctools.js:15:8 searchtools.js:121

   Uncaught TypeError: _ is not a function
at Object.performSearch (searchtools.js:121:29)
at Object.init (searchtools.js:64:16)
at readthedocs-doc-embed.js:1:25956

www.googletagmanager.com/gtag/js?id=UA-17997319-1:1

   Failed to load resource: net::ERR_BLOCKED_BY_CLIENT

I appear to be able to search a local build of the documentation, so it might be that the fix just hasn't been deployed yet.

[lbianchi-lbl]

@dallan-keylogic What's the full URL of the page where this happens? The fix was released after the latest "formally stable" release, so accessing it from idaes-pse.readthedocs.org/en/stable would still show the non-fixed version.

[dallan-keylogic]

@lbianchi-lbl the full URL is https://idaes-pse.readthedocs.io/en/stable/search.html?q=petsc&check_keywords=yes&area=default, so indeed it looks like it hasn't been deployed yet. Switching to "latest" does allow me to search.

[ksbeattie]

I think it works now, @lbianchi-lbl & @dallan-keylogic can you confirm?

I created a new tag 1.13.1 on the 1.13_rel branch (cherry-picked from #932) and updated RTD to use that as the stable build of the docs. There is no 1.13.1 release, this is just a tag in git/github so RTD will find it.

[lbianchi-lbl]

I think it works now, @lbianchi-lbl & @dallan-keylogic can you confirm?

I created a new tag 1.13.1 on the 1.13_rel branch (cherry-picked from #932) and updated RTD to use that as the stable build of the docs. There is no 1.13.1 release, this is just a tag in git/github so RTD will find it.

Yup, seems to be working: https://idaes-pse.readthedocs.io/en/stable/search.html?q=model&check_keywords=yes&area=default