Infinite Loading on search in Kolibri Documentation Search

[siddeshas07]

Observed behavior

When searching for anything on the Kolibri documentation website (https://kolibri-dev.readthedocs.io/), the search function gets stuck in an infinite loop. The search bar shows a loading indicator, but no search results are ever displayed.

Errors and logs

Expected behavior

Upon entering a search term and pressing enter or clicking the search button, the website should display a list of relevant search results matching the query.

User-facing consequences

This issue makes it difficult or impossible for users to find the information they need within the Kolibri documentation, hindering their ability to learn and troubleshoot effectively.

Steps to reproduce

Visit the Kolibri documentation website: https://kolibri-dev.readthedocs.io/
Enter a search term in the search bar (e.g., "install Kolibri").
Press Enter or click the search button.
Observe that the search bar displays a loading indicator but no search results ever appear.

Context

Tell us about your environment, including:

• Kolibri version - NA
• Operating system - MAC
• Browser - Chrome

Tasks

Beta Give feedback

No tasks being tracked yet.

[nucleogenesis]

I just replicated this and seems like search.html is getting a jQuery is not defined error, possibly the cause of the issue. Thanks for the report @siddeshas07 !

[siddeshas07]

hi @nucleogenesis , can you help me locate the search.html https://github.com/learningequality/kolibri/tree/develop/docs , I'm not able to find it under the kolibri , i tried searching in index.rst the but not able find it , i observed kolibri use the reStructuredText for docs , I'm not familiar with it can you please tell the file where search function is present.

[rtibbles]

According to our old friend @benjaoming, the workaround for this may be to add in a specific extension to our extensions configuration:
readthedocs/sphinx_rtd_theme#1452 (comment)

extensions = [
    "sphinxcontrib.jquery",
]

in the docs/conf.py (if there's already an extensions variable in there, this line should be added).

[rtibbles]

Alternatively, it may just be that we need to update the sphinx-rtd-theme package? But it's unpinned, so I am not sure why it's not updated!

[benjaoming]

@rtibbles yes, that looks like the issue caused by Sphinx removing jquery. You should actually pin sphinx-rtd-theme (and everything else, including Sphinx) since that'll avoid breakage in general.

In order to be sure about python package versions installed in the documentation build, check your RTD build log, since the RTD Sphinx builder injects various things during the build - I don't work there anymore, so I'll keep it at the shallow support :)

[rtibbles]

We had the exact opposite issue, unfortunately, where the pinning was causing breakage, hence the unpinning. Will check the log to verify.

[thesujai]

Almost every page where JQuery is used this error can be observed.

Another issue due to unpinning is docs not running on Python version < 3.10.

[rtibbles]

Another issue due to unpinning is docs not running on Python version < 3.10.

This is a wontfix - maintaining docs buildability across all our supported Python versions would require a lot more work.

[benjaoming]

@rtibbles I've fixed this locally and will put a PR: We need to put some lower bound on Sphinx and sphinx-rtd-theme. Otherwise the Read the Docs build process will continue with legacy versions that were baked into Read the Docs for legacy reasons. It doesn't use pip install --upgrade.

maintaining docs buildability across all our supported Python versions would require a lot more work.

Agreed, I don't think you need that, anyways... it needs to run on Read the Docs, not sure if it's built anywhere else? Are developer docs bundled in a release?

[rtibbles]

Yes, only needs to run on readthedocs! Thanks for the PR @benjaoming, I'll take a look!